RESTful API
The NEX Cloud utilises a RESTful API, meaning that it simply provides a portal through which to send or request data from our cloud servers. The HTTP commands GET, PUT, POST, UPDATE, and DELETE are all used to manipulate data through when used with specific URLs.
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.
All connections to the API are over HTTPS for better security. You provide your credentials, and we then provide you with an access key to attach to your requests until the key expires. More details on credentials can be found in the Authentication section.
We recommend that messages sent to and received from the API be formatted as JSON. At this point we only have limited support for XML. The examples here will be in JSON. This can be controlled by the headers shown on the right.
Accept : application/json <!-- Receive a JSON response --> Content-Type : application/json <!-- Send a JSON message --> Accept : application/xml <!-- Receive an XML response --> Content-Type : application/xml <!-- Send an XML message -->
URL Construction
When building a request, there are a few different parameters that may be included in the end URL. It is thus easiest to build your URL in the following way. Note, all words used in the URL are always singular.
In this example, we will retrieve some information about a Controller.
1. The base URL is https://nexcloud.io/v1.0 and will always be your prefix to accessing data from the API.
2. The section you are interested in, for example Controller to retrieve a list of Controllers on your account.
<!-- GET --> https://nexcloud.io/v1.0/Controller
3. (Optional) To only return the specific object you are interested in, you then add its ID to the URL.
<!-- GET --> https://nexcloud.io/v1.0/Controller/5
4. (Optional) You can finally add one more section, which will return the children of the first section. For example, for a Controller, its children would be Devices.
<!-- GET --> https://nexcloud.io/v1.0/Controller/5/Device
5. At the end of your fully constructed URL, you can then append your access token (see the Authentication section below). In the example, the access token is "888aaa777bbb". Parameters on the end of the URL are signalled with a '?' for the first parameter, and then '&' for each additional parameter.
<!-- GET --> https://nexcloud.io/v1.0/Controller/5/Device?access_token=888aaa777bbb
6. A good example of using additional parameters is for navigating long lists of objects. The API always returns 20 results per request, and thus for long lists you will need to sometimes utilise the 'page' parameter to navigate through the entire list. In the example, the second page of devices has been requested from Controller 5, which would encompass the 21st to the 40th Device attached to this controller.
<!-- GET --> https://nexcloud.io/v1.0/Controller/5/Device?access_token=888aaa777bbb&page=2