.. _arbitrator-API-resources-assets: assets --------- The assets resource supports the following operations. .. tabularcolumns:: |p{1.5cm}|p{5cm}|p{8.5cm}| +--------+------------------------+---------------------------------+ | Method | URL | Description | +========+========================+=================================+ | GET | ``/assets`` | Get a list of all assets. | +--------+------------------------+---------------------------------+ | GET | ``/assets/{asset_id}`` | Get a single asset by asset id. | +--------+------------------------+---------------------------------+ | POST | ``/assets`` | Add a new asset. | +--------+------------------------+---------------------------------+ | POST | ``/assets`` | Add multiple new assets. | +--------+------------------------+---------------------------------+ | PUT | ``/assets`` | Updates a single asset. | +--------+------------------------+---------------------------------+ | PUT | ``/assets`` | Updates multiple assets. | +--------+------------------------+---------------------------------+ | DELETE | ``/assets`` | Deletes a single asset. | +--------+------------------------+---------------------------------+ | DELETE | ``/assets`` | Deletes multiple assets. | +--------+------------------------+---------------------------------+ GET ..... ``/assets`` ``/assets/{asset_id}`` * GET Parameters ``asset_id`` - Optional input parameter specifying the specific desired asset. ``/assets/656`` * Response Codes .. tabularcolumns:: |p{5cm}|p{5cm}| +------------------+---------+ | HTTP Status Code | Reason | +==================+=========+ | 200 | Success | +------------------+---------+ * Example Response :: curl -kX GET https://10.13.37.12/api/assets/169 { "assets": [ { "asset_id": "169", "asset_name": "10.13.37.1", "ipaddress": "10.13.37.1", "hostname": "10.13.37.1", "customer": "", "last_method": "snmp_trap", "last_byte_time": "1510782169" } ] } POST, PUT, DELETE Requests and Responses .......................................... Assets can be created, updated, and deleted using POST, PUT, and DELETE respectively. The same request parameter is required for all three requests. This section will describe the desired request parameter and resulting response output. * Request Parameters The ``AssetInput`` object describes the JSON object that can be used to modify a single Asset. The ``AssetInputArray`` object describes the JSON object that can be used to modify multiple Assets. .. note:: The names ``AssetInput`` and ``AssetInputArray`` will be referenced both in this documentation as well as the online interactive documentation that ships with the product. * ``AssetInput`` The following is an example of the required parameter for creating or modifying single Asset. .. note:: The property ``asset_id`` is a required parameter for PUT (updates) and DELETE. It is optional and ignored for POST requests. The ``asset_id`` will be given as part of the response for a successful POST (insert) of an asset. The API does not support the use of ``ipaddress`` as the property for updates and deletes. The property is ambiguous because our system allows duplicate ``ipaddress`` to be inserted into the system. This gets even more complicated when we include the ``customer`` property in the discussion. In order to prevent updates and deletes to assets with duplicate IP addresses, this is a strict requirement for our API. :: { "ipaddress": "(string) Ip address of asset.", "asset_id": "(long): Optional parameter on POST. Required parameter for PUT and DELETE.", "hostname": "(string, optional): Hostname of the asset.", "did": "(string, optional): EM7 specific. Represents EM7 device id.", "mac_address": "(string, optional): Mac address of the asset.", "address": "(string, optional): Physical address of the asset.", "model": "(string, optional): Model of device.", "version": "(string, optional): Version of device.", "manufacturer": "(string, optional): Manufacturer of device.", "timezone": "(string, optional): Timezone of device location.", "description": "(string, optional): Description of device"., "asset_name": "(string, optional): Name or alias of device.", "customer": "(string, optional): Customer name of device.", "site": "(string, optional): Site location name where device resides." } * ``AssetInputArray`` The following is an example of the required POST parameter for adding multiple Assets. .. note:: The property ``asset_id`` is a required parameter for PUT (updates) and DELETE. It is optional and ignored for POST requests. The ``asset_id`` will be given as part of the response for a successful POST(insert) of an asset. :: [ { "ipaddress": "(string) Ip address of asset.", "asset_id": "(long): Optional parameter on POST. Required parameter for PUT and DELETE.", "hostname": "(string, optional): Hostname of the asset.", "did": "(string, optional): EM7 specific. Represents EM7 device id.", "mac_address": "(string, optional): Mac address of the asset.", "address": "(string, optional): Physical address of the asset.", "model": "(string, optional): Model of device.", "version": "(string, optional): Version of device.", "manufacturer": "(string, optional): Manufacturer of device.", "timezone": "(string, optional): Timezone of device location.", "description": "(string, optional): Description of device"., "asset_name": "(string, optional): Name or alias of device.", "customer": "(string, optional): Customer name of device.", "site": "(string, optional): Site location name where device resides." }, { "ipaddress": "(string) Ip address of asset.", "asset_id": "(long): Optional parameter on POST. Required parameter for PUT and DELETE.", "hostname": "(string, optional): Hostname of the asset.", "did": "(string, optional): EM7 specific. Represents EM7 device id.", "mac_address": "(string, optional): Mac address of the asset.", "address": "(string, optional): Physical address of the asset.", "model": "(string, optional): Model of device.", "version": "(string, optional): Version of device.", "manufacturer": "(string, optional): Manufacturer of device.", "timezone": "(string, optional): Timezone of device location.", "description": "(string, optional): Description of device"., "asset_name": "(string, optional): Name or alias of device.", "customer": "(string, optional): Customer name of device.", "site": "(string, optional): Site location name where device resides." } ] * Response Code .. note:: Delete will only return a response code. ``200`` * Response Body Below is an example of successful Insert or Update. Result may contain one or many assets. The ``asset_id`` must be saved by the application in order do make any subsequent Updates or Delete requests. ``AssetResult`` :: { "assets": [ { "asset_id":"656", "asset_name":"", "ipaddress":"192.168.1.1", "hostname":"test hostname", "customer":"Customer1", "last_method":"", "last_byte_time":"0" } ] } * Other Possible Responses .. tabularcolumns:: |p{2.5cm}|p{6cm}|p{6cm}| +---------------+------------------------------------------------------------+---------------------------------------+ | Response Code | Reason | Remedy | +===============+============================================================+=======================================+ | 200 | Success | | +---------------+------------------------------------------------------------+---------------------------------------+ | 400 | Exception: UPDATE error: ``asset_id`` property required. | Include ``asset_id`` in request body | +---------------+------------------------------------------------------------+---------------------------------------+ | 400 | Exception: UPDATE error: Received null asset input. | See ``AssetInput`` | +---------------+------------------------------------------------------------+---------------------------------------+ | 400 | Exception: DELETE: error: ``asset_id`` property required. | Include ``asset_id`` in request body | +---------------+------------------------------------------------------------+---------------------------------------+ | 400 | Exception: DELETE error: Received null asset input.. | See ``AssetInput`` | +---------------+------------------------------------------------------------+---------------------------------------+ POST ....... ``/assets`` * Example Curl Request Command: :: curl -k -w '\nRESP_CODE: %{response_code}\n' -X POST https://10.13.37.12/api/assets - d'{"did": "1234", "hostname":"test hostname", "ipaddress":"192.168.100.1", "alias":"alias natted ip address", "model":"test model", "version":"test version", "manufacturer":"test vendor", "timezone":"test timezone", "description":"test description", "address":"test physical address", "customer":"Test Customer1", "site":"Test Site1"}' Output: :: {"assets": [ {"asset_id":"657", "asset_name":"", "ipaddress":"192.168.100.1", "hostname":"test hostname", "customer":"Test Customer1", "last_method":"","last_byte_time":"0"} ]} RESP_CODE: ``200`` PUT ..... ``/assets`` * Example Curl Request .. note:: ``asset_id`` was included. Command: :: curl -k -w '\nRESP_CODE: %{response_code}\n' -X PUT https://10.13.37.12/api/assets - d'{"asset_id":"657", "did": "1234", "hostname":"test hostname2", "ipaddress":"192.168.100.1", "alias":"alias natted ip address", "model":"test model", "version":"test version", "manufacturer":"test vendor", "timezone":"test timezone", "description":"test description", "address":"test physical address", "customer":"Test Customer1", "site":"Test Site1"}' Output: :: {"assets": [{"asset_id":"657", "asset_name":"", "ipaddress":"192.168.100.1", "hostname":"test hostname2", "customer":"Test Customer1", "last_method":"", "last_byte_time":"0"}] } RESP_CODE: ``200`` DELETE ......... ``/assets`` Command: :: curl -k -w '\nRESP_CODE: %{response_code}\n' -X DELETE https://10.13.37.12/api/assets - d'{"asset_id":"657", "did": "1234", "hostname":"test hostname2", "ipaddress":"192.168.100.1", "alias":"alias natted ip address", "model":"test model", "version":"test version", "manufacturer":"test vendor", "timezone":"test timezone", "description":"test description", "address":"test physical address", "customer":"Test Customer1", "site":"Test Site1"}' Output: RESP_CODE: ``200``