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:

Open an API development environment program (such as Postman, which may be downloaded at www.getpostman.com) that supports HTTP or WebSocket requests.
Enable authentication and configure the required authentication cookies and headers as described in Authentication.
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]"

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.

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).

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.

Sample Result #1: All Properties Were Set Successfully

In this scenario, the following POST request was sent to the device:

Copy

"Device": {
    "Ethernet": {
        "Adapters": [ null,
            {
                "IPv4": [
                    {
                        "StaticAddresses": [
                            {
                                "Address":"10.254.44.3",
                                "SubnetMask":"255.255.240.0"
                            }
                        ],
                        "StaticDefaultGateway":"10.10.10.1"
                    }
                ]
            }
        ]
    }
}

For this request, all the requested property changes (IPV4 Static Address, IPV4 Static SubnetMask, and IPV4 StaticDefaultGateway) were successful.

The Response object generated for the POST request is shown below:

Copy

"Actions": [
    {
        "TargetObject":" Ethernet",
        "Operation":"SetPartial",
        "Results": [
            {
                "Path":"Device.Ethernet",
                "StatusId":0,
                "StatusInfo":"OK"
            }
        ]
    }
]

Sample Result #2: At Least One Property Application Failed

In this scenario, the following POST request was sent to the device:

Copy

"Device": {
    "Ethernet": {
        "Adapters": [ null,
            {
                "IPv4": [
                    {
                        "StaticAddresses": [
                            {
                                "Address":"10.254.44.3",
                                "SubnetMask":"255.0"
                            }
                        ],
                        "StaticDefaultGateway":"1"
                    }
                ]
            }
        ]
    }
}

The IPV4 Static Address is valid, but the IPV4 StaticSubnetMask, and IPV4 StaticDefaultGateway properties are invalid.

The Response object generated for the POST request is shown below:

Copy

"Actions": [
    {
        "TargetObject":" Ethernet",
        "Operation":"SetPartial",
        "Results": [
            {
                "Path":"Device.Ethernet.Adapters[1].IPv4.StaticAddresses[0].SubnetMask”,
                "StatusId":-1,
                "StatusInfo":"value out of range"
            },
            {
                "Path":"Device.Ethernet.Adapter[1].IPv4.StaticDefaultGateway",
                "StatusId":-1,
                "StatusInfo":"value out of range"
            },
            {
                "Path":"Device.Ethernet.Adapters[1].IPv4.StaticAddresses[0].Address”,
                "StatusId":0,
                "StatusInfo":"OK"
            }
        ]
    }
]

NOTE: A Results object is created for each property in the case where at least one property value failed to be applied. This avoids any ambiguity as to which property settings were actually applied.

Sample Result #3: A Property Setting Requires a Device Restart

In this scenario, the following POST request was sent to the device:

Copy

"Device": {
    "Ethernet": {
        "Adapters": [ null,
            {
                "IPv4": [
                    {
                        "StaticAddresses": [
                            {
                                "Address":"10.254.44.3",
                                "SubnetMask":"255.255.240.0"
                            }
                        ],
                        "StaticDefaultGateway":"10.10.10.1"
                    }
                ]
            }
        ]
    }
}

The Response object generated for the POST request is shown below, indicating that a restart is required to apply these settings to the device:

Copy

"Actions": [
    {
        "TargetObject":" Ethernet",
        "Operation":"SetPartial",
        "Results": [
            {
                "Path":"Device.Ethernet",
                "StatusId":1,
                "StatusInfo":"Reboot Required"
            }
        ]
    }
]

Have feedback on this document? Contact docfeedback@crestron.com.

All brand names, product names and trademarks are the property of their respective owners. Certain trademarks, registered trademarks, and trade names may be used to refer to either the entities claiming the marks and names or their products. Crestron disclaims any proprietary interest in the marks and names of others. Crestron is not responsible for errors in typography or photography. Specifications are subject to change without notice.