6.0 Devices APIs

WAS THIS PAGE HELPFUL? Leave Feedback

6.0 Devices APIs

6.1 Query Devices

Retrieve devices by query. There are two kinds of queries supported:

1. Retrieving a single device. Retrieves exactly one device wrapped by an XML <device> element
2. Retrieving one or more devices . Retrieves 1..n device objects wrapped by an XML <devices> collection

6.1.1 Method: GET Device

GET /api/devices?query=(query criteria see below)

6.1.2 Method: GET a single device by identification

GET /api/devices/{deviceIdentification}

6.1.3 HTTP Query and Path Parameters

Note: **If neither a deviceIdentification path parameter or query query parameter is not provided, all devices will be retrieved.

6.1.4 HTTP Headers

6.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

6.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all devices, with shallow depth
   GET /api/devices
2. query for all devices, with deep depth
   GET /api/devices?depth=deep
3. query for a single device identified by 127.0.0.1, with depth of shallow
   GET /api/devices/127.0.0.1
4. query for a single device identified by 127.0.0.1, with depth of deep
   GET /api/devices/127.0.0.1?depth=deep
5. a like query to find all devices starting with identification of 172.28.113.* and filter by host name
   GET /api/devices?query=identification like '172.28.113%' and d.hosts.hostName = 'qa-sles-11-64-2'
6. a simple or query on the display names ordered by name (displayName)
   GET /api/devices?query=displayName = 'demo' or displayName = 'malbec' order by name
7. query for one or more display Names using in query syntax
   GET /api/devices?query=name in ('demo','malbec','sql-2008','127.0.0.1'')

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a device identifier in the path parameter is always wrapped with a single <device> entity element. Here is an XML example of the result of a query finding one device. All fields are displayed as attributes.

<device id="1"
  identification="127.0.0.1"
  displayName="127.0.0.1"
  description="Device localhost"/>

Result of queries are always wrapped in a <devices> collection element, with one or more <device> subelements.

<devices>
  <device id="1” identification="127.0.0.1"
    displayName="127.0.0.1"
    description="Device localhost"/>
  <device id="2” identification="172.28.113.166"
    displayName="QA server"
    description="Device for QA Testing"/>
</devices>

Host and Monitor Server collections are only displayed when depth = deep. These collections are represented as elements.

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Shallow Response Data - XML - JSON
  Deep Response Data - XML - JSON

6.2 Create Devices

Creates a batch (1..n) of new devices in foundation database. Devices will be created if they do not exist. If a device exists, it will be updated. You can also specify one or more hosts to be created or associated with the device. Note these hosts will be created if they do not already exist in the system.

If one or more device creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Device creation/update operation is returned back in the resultset described below with a status of success or failure.

6.2.1 Method: POST

POST /api/devices

6.2.2 HTTP Headers

6.2.3 Post Data Attributes and Elements

6.2.4 XML POST Data Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<devices>
  <device displayName="device-900" identification="172.28.128.100">
    <hosts>
      <host hostName='abc.com' description='Host ABC'/>
      <host hostName='def.com' description='Host DEF'/>
    </hosts>
  </device>
</devices>

More Post Data Examples: XML - JSON

6.2.5 HTTP Status Codes

200 - Zero or more devices were created without any internal server errors
500 - An internal server error occurred

6.2.6 Example Response

In this example, we use the POST data above. One device was attempted to be created. Additionally, we tried to add two hosts to the device.
Note that the results collection also returns the location of the created or updated device which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="1" failed="0" entityType="Device"
       operation="Update" warning="0" count="1">
  <result>
    <entity>172.28.128.100</entity>
    <location>
    http://localhost/api/devices/172.28.128.100</location>
    <status>success</status>
  </result>
</results>

6.3 Delete Devices

Deletes one or more devices from the Collage database. There are two methods of deletion:

1. Delete without post data, passing in one or more devices names on URL path
2. Delete with post data, passing in device identifications in post data

6.3.1 Method: DELETE without POST Data

DELETE /api/devices/127.0.0.1

where 127.0.0.1 is a single device identification to be deleted

DELETE /api/devices/127.0.0.1,172.28.113.166
where the comma-separated list of two device identifiers. Note that no-spaces are allowed in this HTTP path segment.

6.3.2 Method: DELETE with POST Data

DELETE /api/devices

The post data should be formatted like a POST payload, but the only required field is the device Identification. Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<devices>
  <device identification="172.28.113.166” />
  <device identification="172.28.113.168” />
</devics>

6.3.3 HTTP Headers

6.3.4 HTTP Status Codes

200 - Hosts were deleted successfully
500 - An internal server error occurred

6.3.5 Example Response

<results count='2' success='2' failure='0' entityType=Device operation=’Delete’>
  <result status='success' entity='172.28.113.166’
       location='http://localhost/monitor/api/devices/172.28.113.166’' />
  <result status='success' entity='172.28.113.168’
       location='http://localhost/monitor/api/devices/172.28.113.168’ />
</results>