GUIDELINES

The SCR API is a standard REST-API and in that respect, there will be few surprises for your developers. However, to guarantee the future performance and stability of the application, we would like to stress that the guidelines listed below have to be taken into account when interacting with the API.

Alway use event notifications instead of polling

Polling the SCR API should be avoided since it will create unnecessary transactions on the blockchain network and therefore can affect the performance of your integration but also of the other parties in the network.

Therefore, you should use the event notification mechanism to receive updates and new releases, and process them in your internal system. This is a very simple mechanism where you register a callback url once and afterwards, all release events will be notified on that callback url. When an event comes in your system can retrieve the details by calling the API, but you should not poll the API for the containers in your transport management system every x minutes.

Field lengths and definitions

All text fields have a default length of 255 characters. Only the terms and conditions field has an unlimited length.

Error handling and time-outs

Since the SCR API connects to other servers in the network, time-outs and other infrastructure related errors are always possible and should be taken into account during development. Retrying a call after a few minutes is the easiest way to deal with this, since most transactions are not time critical.

Simultaneous transactions

The SCR API can accept simultaneous requests without side effects as long as you are retrieving release information. So, when you send a number of simultaneous calls to the GET /releases endpoint, this will not slow down the responses much.

However, calls that change data or retrieving pins are essentially processed sequentially by the SCR API so sending a lot of requests simultaneously will slow down the responses and this should be taken into account at your side. You can send the requests simultaneously and set the time-out high enough, or you can send only a few requests at the same time.

For high volumes of requests we also offer a batch API which can process up to 20 requests simultaneously, providing a higher throughput.

Please contact us if you want to use these BATCH endpoints.