RACE RESULT Systems can upload passings and status information to RACE RESULT’s servers using their inbuilt GSM Modems / LAN connection.
The devices must have the Upload function enabled with an active internet connection to be able to send information to the RACE RESULT servers.
REST API Interface
The REST interface allows retrieval of data from systems which are uploading to the RACE RESULT servers, this includes RACE RESULT decoders which are uploading via TCP and Track Boxes. The REST API allows for commands to be sent to decoders for remote control.
For communication with the REST API you will need an API Keys for the Customer ID you wish to access.
Endpoint URL
All commands for the REST API interface should point to:
https://rest.devices.raceresult.com
You should ensure to include Connection: close in all calls to ensure the connections are not left open which may cause our servers to activate security protocols which will block your IP address.
Authorization
In order to access the REST API you will need to authenticate using an API key for the Customer ID which will generate an authorization token.
Commands
Commands available through the rest interface include:
- Listing available devices and statuses
- Listing available files from systems
- Retrieving passings
- Send decoder commands (Remote Control)
- Check REST interface status
Commands are sent via either GET or POST requests (according to the specific request) and will use the token generated during authorization.
Response data is returned in JSON format, according to the command sent in specified data Models.
URL Parameters
{customerID} - The ID of the customer which should be queried (Integer)
{deviceID} - The ID of the device which should be queried (String)
{FileNo} - The file number to be queried (Integer)
HTTP Status Codes
200 - OK
400 - Bad Request
500 - Internal Server Error
Models
In the REST API interface all responses are returned in JSON format, data fields are returned in alphabetical order.
Basic Example
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.