Here are some example RESTful interactions with the API.

Please be aware that actions performed on all of your API objects are final - if you DELETE something, it will be deleted from the system. Whilst you are getting used to the system, it is recommended you strictly use GETs to retrieve your data, or create new objects to test deleting on.

GET

GET requests have no body, and cannot alter the state of anything on the server. They are simply used to retrieve information. These are your most common requests for retrieving data from the API. You'll essentially just need to create a GET request in your chosen HTTP library, add the required headers and the URL, and execute it.

JSON GET Request

<!-- GET -->
https://nexcloud.io/v1.0/Controller/1

<!-- HEADER -->
Accept : application/json

JSON GET Response

<!-- RESPONSE -->
https://nexcloud.io/v1.0/Controller/1

<!-- HEADER -->
Content-Type : application/json

<!-- BODY -->
{
  "ControllerID": 1,
  "Name": "NEX DMS4080 Example",
  "Description": "Demo controller in NEX office.",
  "Brand": "NEX",
  "Model": "DMS4080",
  "Revision": "110",
  "SoftwareVersion": "1.2",
  "FirmwareVersion": "1.0",
  "DatabaseVersion": "1.0",
  "SerialNumber": "987654321",
  "ActivationDate": "2017-04-26T23:28:15+00:00",
  "RegistrationDate": "2017-04-26T23:28:15+00:00",
  "AccountID": 123456789,
  "SiteID": 6789,
  "MinimumUpdateTier": 2,
  "WatchdogDate": "2017-05-29T03:06:06+00:00",
  "Modified": "2017-05-23T03:05:38+00:00"
}

POST

Requires additional permissions, please contact support.

POST requests have a body, and create a new object within the system (generally). Similar to this are PUT and UPDATE: PUT will effectively be a POST if the object doesn't exist, or an UPDATE if the object exists. UPDATE simply updates a given object, or fails if the object doesn't exist. POST will fail if the object already exists.

Additionally, when using POST, you submit an object without the Id number for it. The API will then respond with the item if it was successfully created, along with its new Id number.

Note: The Communications field is a String with JSON formatting.

JSON POST Request

<!-- POST -->
https://nexcloud.io/v1.0/Controller/1/Device

<!-- HEADER -->
Accept : application/json
Content-Type : application/json

<!-- BODY -->
{
  "Name": "Example Device",
  "Brand": "Example Brand",
  "Model": "Example Model",
  "Version": "1.23",
  "Location": "Example Location",
  "Communications": "{\"Port\": \"/dev/ttyAMA0\", \"Serial\": {\"Echo\": 0, \"Parity\": \"None\", \"BaudRate\": 9600, \"DataBits\": \"8\", \"StopBits\": \"1\"}, \"Address\": \"40\", \"Channel\": \"ModbusRTU\", \"RegisterOffset\": -1}",
  "DataPointGroupID": 9,
  "ControllerID": 1
}

JSON POST Response

<!-- RESPONSE -->
201 Created
https://nexcloud.io/v1.0/Controller/1/Device

<!-- HEADER -->
Content-Type : application/json

<!-- BODY -->
{
  "DeviceID": 2,    // Note the Device ID generated for you, and returned in response.
  "Name": "Example Device",
  "Brand": "Example Brand",
  "Model": "Example Model",
  "Version": "1.23",
  "Location": "Example Location",
  "Communications": "{\"Port\": \"/dev/ttyAMA0\", \"Serial\": {\"Echo\": 0, \"Parity\": \"None\", \"BaudRate\": 9600, \"DataBits\": \"8\", \"StopBits\": \"1\"}, \"Address\": \"40\", \"Channel\": \"ModbusRTU\", \"RegisterOffset\": -1}",
  "DataPointGroupID": 9,
  "ControllerID": 1
}

DELETE

Requires additional permissions, please contact support.

DELETE requests will, if you have the sufficient rights, simply delete the object. The URL used to specify it must be direct and only specify one object - deleting groups of objects isn't possible. When called, there isn't any response body, just a 200 OK if the action succeeded. As there is no body in the request or the response, the JSON or XML header will only be useful for unsuccessful attempts, when an error will be returned.

Requires additional permissions, please contact support.

DELETE Request

<!-- DELETE -->
https://nexcloud.io/v1.0/DataPoint/5

<!-- HEADER -->
Accept : application/json

DELETE Response

<!-- RESPONSE -->
https://nexcloud.io/v1.0/DataPoint/5

<!-- HEADER -->
Content-Type : application/json

Related articles

Browser not supported