Make API Calls

The DM NVX API supports synchronous and asynchronous retrieval of data and synchronous setting of data. The API uses CresNext objects to set or retrieve the configuration.

NOTE: Most of the following procedures use Postman as an example API development environment program. While these procedures can apply to any API development environment program, the actual implementation may vary by program. Refer to the program's documentation for more information on using it to make API calls.

Getting Started

To access the DM NVX API interface:

  1. Open an API development environment program (such as Postman, which may be downloaded at www.getpostman.com) that supports HTTP or WebSocket requests.
  2. Enable authentication and configure the required authentication cookies and headers as described in Authentication.
  3. Issue an HTTP or WebSocket request that includes the required HTTP method, headers, and parameters as outlined in the sections that follow. Authentication must be enabled and the cookies must be sent with every request.

If accessing the API layer via cURL, the cURL command must be formatted as follows, with any parameters entered after the authorization token in the appropriate format (multipart/form-data or application/json):

cURL Syntax for GET Requests

Copy 
curl "https://[IP address]/[path]" -H "cookie: userstr=[value];Path=/;Secure;HttpOnly; userid=[value];Path=/;Secure;HttpOnly; iv=[value];Path=/;Secure;HttpOnly; tag=[value];Path=/;Secure;HttpOnly;" -H "Referer: [IP address]"


cURL Syntax for POST Requests

Copy 
curl "https://[IP address]/[path]" -X POST -d [JSON payload] -H "cookie: userstr=[value];Path=/;Secure;HttpOnly; userid=[value];Path=/;Secure;HttpOnly; iv=[value];Path=/;Secure;HttpOnly; tag=[value];Path=/;Secure;HttpOnly;" -H "Referer: [IP address]" -H "X-CREST-XSRF-TOKEN: [value]"


The format of the cURL command may also be used to make web calls in other programming languages.

HTTPS GET Requests

The client can get the current state of an object by issuing a GET request with the path defined by the object.

A sample GET request and response is provided below.

  • Request URL: https://$ip/Device/Ethernet/HostName
  • Response: {"Device":{"Ethernet":{"HostName":"[value]"}}}

WebSocket GET Requests

The client can get the current state of an object by issuing a get request with the path defined by the object.

NOTE: Once the WebSocket interface is open, all requests made inside are transparent. An IP suffix and a request URL are not required (only a request payload).

A sample GET request and response is provided below. GET requests should always be in URI format.

  • Request Payload: /Device/DiscoveryConfig/DiscoveryAgent
  • Response: {"Device":{"DiscoveryConfig":{"DiscoveryAgent":true}}}

HTTPS POST Requests

Setting data requires the user to POST the CresNext object to /Device. The object can be a partial object. Only the properties sent will be applied.

The CREST-XSRF-TOKEN header from the initial POST request to the device must be added as a header in any subsequent HTTPS POST request, where the header name is X-CREST-XSRF-TOKEN and the header value is the value of the CREST-XSRF-TOKEN header. For more information, refer to Authentication.

NOTE: If the X-CREST-XSRF-TOKEN is not provided with a POST request, all cookies will be invalidated, and you must reauthenticate against the device.

In the following example, the HostName property is modified by posting to /Device. The request payload is formatted as raw JSON.

  • Request URL: https://$ip/Device/Ethernet/HostName
  • Request Payload: {"Device":{"Ethernet":{"HostName":"MyDevice"}}}

The response to the POST request contains an Actions object in the following format:

Copy
{
    "Actions":[
        {
            "Operation":"SetPartial",
            "Results":[
                {
                    "Path":"Device.Ethernet",
                    "Property":"HostName",
                    "StatusId":1,
                    "StatusInfo":"Reboot needed"
                }
            ],
            "TargetObject":"Ethernet",
            "Version": "2.1.0"
        }
    ]
}


WebSocket POST Requests

Setting data requires the user to POST the CresNext object to /Device. The object can be a partial object. Only the properties sent will be applied.

NOTE: Once the WebSocket interface is open, all requests made inside are transparent. An IP suffix and a request URL are not required (only a request payload).

The CREST-XSRF-TOKEN header from the initial POST request to the device must be added as a header in any subsequent WebSocket POST request, where the header name is X-CREST-XSRF-TOKEN and the header value is the value of the CREST-XSRF-TOKEN header. For more information, refer to Authentication.

NOTE: If the X-CREST-XSRF-TOKEN is not provided with a POST request, all cookies will be invalidated, and you must reauthenticate against the device.

In the following example, the IsEnabled property is modified by posting to /Device. POST requests should always be in standard JSON format.

  • Request Payload: {"Device":{"CloudSettings":{"XioCloud":{"IsEnabled":true}}}}

CAUTION: Sending an empty object will delete that object. For example, sending {"Device":{"DeviceSpecific:{}}} would delete the DeviceSpecific object.

The response to the POST request is shown below.

Telemetry Data

The web services allow receiving asynchronous events when properties change on the device. Some objects do not support generation of these events. Documentation for the object will indicate if the event support is absent on the device.

The following request can be made on an object:

GET /Device/[Object]/Longpoll

The long poll will return under two conditions:

  • Data has changed: When data changes, the appropriate CresNext object will be sent back in the response.
  • Timeout: In the case of a timeout, the web services client must perform the request again.

Long polls can be used to get asynchronous data. The response will either be a timeout or a partial object with only the changed properties.

For the HostName example GET, the long poll is shown below. The following request will issue a long poll GET /Device/Longpoll.

  • Request URL: https://$ip/Device/Longpoll
  • Response: {"Device":{"Ethernet":{"HostName":"MyDevice1"}}}

For WebSocket connections, a long poll request for the WebSocket will not be present. Instead, updates to the object are sent asynchronously to the web UI.

Results Object

The Results object is a component of the Action object, which is included in PUT messages reporting the property application status. This object contains a success or failure status from the receiving side of the requested property updates.

The StatusId and StatusInfo results objects should be used to determine if there were any errors when setting the data.

The Results object contains the following components:

  • Path: The location of the property within the specified CresNext object. This will always start with Device.
  • StatusId: A number code that corresponds with an error or informational message as shown below:
    • <0 : Error codes
      • -1: The value is out of the specified range
      • -2: The property is read only
      • -3: A required property is missing
      • -4: Generic error
    • 0: OK
    • >0: Informational
      • 1: A device restart is required for the updated properties to take effect
      • 2: An OOTB (Out of the Box) application reset is required
      • 3: The property is unsupported
  • StatusInfo: An optional field that specifies additional information regarding the operation.

Sample Results

The following sample results are provided to show common results objects that can be returned after sending a POST request.