Controller Flow

Owned by Darian Cabot
23 Jun 2017
4 min read

This page contains both a general overview to get you started, as well as a specifics guide for going over everything you need to know. This page is for anyone with a product that they would like to send data to the NEX API.


Controller Flow

A Controller connecting to our system would follow this general pattern upon powering up (assuming it had already been configured fully):

1. Upon receiving power, the Controller would (after initialising its main components) send a request for a new access token from our API.

<!-- POST -->
https://nexcloud.io/v1.0/Token?

2. If successful in retrieving the access token, the controller can then query the API for its own information.

<!-- GET -->
https://nexcloud.io/v1.0/Controller/123?access_token=888aaa777bbb

3. After reading your Controller's information, it should then check the list of devices. It can then update its own configuration to match if required.

<!-- GET -->
https://nexcloud.io/v1.0/Controller/123/Device?access_token=888aaa777bbb

4. Now that your controller has a token, as well as its Controller and Device information, it can retrieve all the Data Points that it will be talking to and posting data for.

<!-- GET -->
https://nexcloud.io/v1.0/Device/555/Datapoint?access_token=888aaa777bbb

5. After collecting all the DataPoints for all the Devices, your Controller is now ready to begin sending its data to the cloud. The specific format for this can be seen in the Sending Data section. All incoming data is sent to the data stream URL, where it will be queued up and then processed by the NEX Cloud servers.

<!-- POST -->
https://nexcloud.io/v1.0/Stream?access_token=888aaa777bbb


Authentication

Authentication for a Controller is done in the similar way as documented on the general Authentication page, in that Tokens must be requested and renewed using your specific credentials.

The difference for a controller is that the token is requested using a Controller ID and Controller Secret, instead of a Username and Password.

All authentication credentials are provided through OAuth2 using the API endpoint https://nexcloud.io/V1.0/Token. To begin with, all your products will have a specific Client identification key and secret. This is used to categorise/group all your Devices together through your organisation's client credentials. Additionally, each individual Controller that connects to the API will have its own Controller Id and secret. So, essentially, there's a username and password for your company, and then a username and password for each of your Controllers. By correctly providing these to the API, you will be given an API token with which to communicate to the API.

The easiest way to retrieve an access token is by using a POST request to https://nexcloud.io/v1.0/Token, along with the header

'Content-Type : application/x-www-form-urlencoded'

The body of this post is then your credentials for this request.


See:

<!-- Controller request, requires:
    Client Id, Client Secret,
    Controller Id, Controller Secret,
    as well as the scope of the request (ie. 'controller')
    * Note that these values are just an example,
      you will need to substitute your actual values into this. *
-->

<!-- POST -->
https://nexcloud.io/v1.0/Token

<!-- HEADER -->
Content-Type : application/x-www-form-urlencoded
Accept       : application/json
 
<!-- BODY -->
grant_type=client_credentials&client_id=5a5b&client_secret=abc123&controller_id=111aa
    &controller_secret=456&scope=controller

<!-- Body explanation:
    clientId = 5a5b         - this will be the same for all of your products
  & clientSecret = abc123   - this will be the same for all of your products
  & controllerId = 111aa    - this will be different for each physical object
  & controllerSecret = 456  - this will be different for each physical object
  & scope = controller      - this will be the same for all of your products
-->

Authentication Response

After sending the request, you will receive a response. If everything is in order, your request will be successful and you will receive a response like this.

The body will be formatted as JSON or XML depending on your Accept header in the request. It will contain four members:

  1. The access token.
  2. The expires in value, which is how long the value will be valid for in seconds. This is not constant between all token types, so make sure you check your token expiry time. The example token here has a 2 week period for use, which would be the maximum period you'll ever see.
  3. The token type value, which will be bearer. This is simply to tell you that you must attach this token to each request to use it.
  4. The scope of the token, which is that it can access everything a controller can access.
<!-- RESPONSE -->
https://nexcloud.io/v1.0/Token

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

<!-- BODY -->
response :
    access_token : new934token1234
    expires_in   : 12096000
    token_type   : Bearer
    scope        : controller




NEX Terms of Service • Request NEX API access • Copyright © 2017 NEX Data Management Systems Pty Ltd. All rights reserved.