This basic example looks at the first steps in using the REST interface, it looks at how to:

• Retrieve an access token
• Check which systems are online for the customer
• Check System Status
• Retrieve the passings from a specified file
• Retrieve all passings from a specified starting point

This example was achieved using Postman a useful tool for API development, we are hiding the auto-generated headers and information. This example is purely exemplary of how the commands can be used, please reference the full command documentation for detailed descriptions of functions. 

Generating Token

A POST request is sent to the token command using the apikey

Request:

Response:

This access token will be used for all subsequent commands.

Listing Available Systems

We now want to see which devices are currently available, so call the devices command with the parameter connected=true, the authorization token is now sent in the header as a bearer authorization.

Request:

Response:

With this, we receive a list of all systems which are currently connected to the Customer ID specified in the URL to which the API key corresponds. We have the current running information of the system and the full decoder status. 

In particular, we will take note of the FileNo (52), this indicates the device's current file number which we will use to retrieve the desired passings. 

Check System Status

Once we have the device we want to use, we can periodically check the system status, this allows us to check if it is still connected, or displaying any errors. 

The devices command when used with a specific device ID in the URL returns the status for that system. 

Request:

Response:

Focusing on the DecoderStatus we can see that ErrorFlags returns a value of 16 which is due to the Loop Error on the system (with no loop connected). 

Retrieve Specific Passings File

Expanding on this further we can now call the passings file which we know is currently active (52), this command will attempt to return all passings for that file.

Note that the maximum which can be returned in a single call is 10,000, if the command returns more than 10,000 it will return an error and you will need to use the fromPassing and amount parameters additionally.

It is recommended to always specify an amount of passings to return to prevent running into errors. 

Request:

Response:

Here the full passing record is returned, you may wish to only select fields which are relevant to your application, a full explanation of the passing record is available here.

Retrieve All Passings from Starting Reference

During timing you may want to simply return all passings from when you open a connection regardless of the file number, this can be achieved using the passings command with no file number specified in the URL path but instead supplied as query parameters. 

In this example we want to retrieve all passings starting from file 52 onwards, a new file was created (53) with a marker to signify the start of the file. 

Request: 

Response:

We have PassingNo 3 from file 52 returned and then the next passing is PassingNo1 from file 53. In subsequent calls, we could now start from this reference point.