Skip to main content
Version: 11.0.0

signageOS REST API

Introduction​

signageOS helps any developer to build apps for digital signage devices (SOC displays and media players) and remotely manage large networks of these devices in a standardized way. No matter what display you are using, all APIs work across all of them.

Resources​

Device Plans​

You need signageOS CloudControl with Device Plan that enables you to generate token and use REST API.

REST API Authentication​

For REST API your application needs to be authenticated using request Header: X-Auth which is unique per user and organization.

Where to get Organization token XAuthOrganization​

Organization token is referred to as XAuthOrganization in the API.

  1. Go to Organizations section in signageOS Box and generate your token_id & token_secret.
  2. Use it as X-Auth header separated by colon - __TOKEN_ID:__TOKEN_SECRET__.

Where to get Account token​

Account token is referred to as XAuthAccount in the API.

  1. Go to Account profile section in signageOS Box and generate your Account token_id & token_secret.
  2. Use it as X-Auth header separated by colon - __TOKEN_ID:__TOKEN_SECRET__.
# X-Auth = client_id:client_secret

curl -XGET -H "X-Auth:
87e376c08d16XXXXb796294744:5ef829c933aXXXX710f5388a27fee" \
  https://api.signageos.io/v1/device

REST API Request Quota and Rate Limiting​

signageOS REST API automatically applies quotas on REST requests. The quota is counted per IP address of the Request origin.

The quota is set to 200 requests per second for instant response and 500 queued requests with a slightly delayed response based on request type and performance.

If you reach the quota API returns 429 Too Many Requests response.

Fair User Policy​

Based on your Device Plan you are eligible for a given number of API request per device per day. If you exceed the quota for 2 consecutive months it might result in a temporary ban and you will be notified via email.

Pagination​

There is enforced maximum length of data that can be returned in a single response. If there's more data available, than the limit allows, data will be returned in multiple pages. Cursor based pagination will be used. https://jsonapi.org/profiles/ethanresnick/cursor-pagination/#auto-id-query-parameters

Parameter limit can be used for setting the page size. Setting the limit over the max allowed limit will result in error. Beware not to change the limit in the middle of the process of fetching pages. If a different limit is specified, process needs to be started over from the first page.

Request without additional parameters will return the first page. If there are more data available, the response will contain a header "Link" that will contain the link to the next page, e.g. <https://api.signageos.io/v1/device?until=2021-11-01T00%3A33%3A38.918Z>; rel="next". Then by performing another request with the link next page will be returned. Each response will contain a link to the next page until there are no more data left.

Url structure​

List parameters​

There are two ways lists could be encoded:

  • ... <LIST_PARAM_NAME>=<VALUE_0>&<LIST_PARAM_NAME>=<VALUE_1>&<LIST_PARAM_NAME>=<VALUE_2> ...
  • ... <LIST_PARAM_NAME>=<VALUE_0>,<VALUE_1>,<VALUE_2>...

For example, list with values uid1, uid2, uid3, encoded in URL as parameter deviceUid will look like this:

deviceUid=uid1&deviceUid=uid2&deviceUid=uid3

or

deviceUid=uid1,uid2,uid3

In the case of comma-separated values, any string value containing a comma should be escaped.

Asynchronous REST API Requests​

While some of API endpoints can be “fire and forget”, i.e. there is no need to report back to the client, for example, when initiating a bulk actions. For others, the client may need a response, but can't get it in the original request because of the long processing time, i.e. in case of firmware upgrade request or Applet operations. In those cases, we have to do a "pre-flight" check and connect directly with device to execute the action, which can be a time-consuming process, often better performed asynchronously.

For these asynchronous operations (typically all /device/xxxx endpoints) we adopted a polling strategy. Clients can retrieve the results of asynchronous requests by polling a special endpoint that will return the result of the request, once it's available.

Standard Flow Example​

  1. The client sends the PUT request - set brightness to 100% - to the server to begin the operation.
  2. The server accepts the request, confirming by 200 OK message.
  3. The asynchronous process begins on the server side, triggering desired function - connecting to device, setting a brightness and confirming the value was set and accepted by the device.
  4. Finally, the server finished the action by receiving a confirmation from the device - brightness successfully set to 100%.

During this process, the client polls the GET URI of the brightness endpoint. The server returns the status of the last request:

{
  "uid": "deed07d35fdxxx",
  "deviceUid": "e824fcd24a4fxxx",
  "createdAt": "2022-07-22T12:06:45.540Z",
  "succeededAt": "2022-07-22T12:06:55.850Z",
  "failedAt": null,
  "brightness1": 90,
  "brightness2": 40,
  "timeFrom1": "09:00:00",
  "timeFrom2": "20:00:00"
}

Status of the operation is available under succeededAt and failedAt keys. If the request succeeeded, succeededAt will be set. If it failed, failedAt will be set. If non of the two are set, it means that the request is still pending.

Flow diagram of async requests

Important consideration​

In the polling pattern, the client must decide how frequently to poll the URL and when to give up. One common choice is exponential backoff, which increases the interval between checks until a maximum interval is reached or the response (succeededAt/failedAt) is received.

Authentication​

Organization authentication using token_id:token_secret format.

To authenticate:

  1. Go to Organizations section in signageOS Box
  2. Generate your token_id & token_secret
  3. Use as X-Auth header: token_id:token_secret

Example: 87e376c08d16XXXXb796294744:5ef829c933aXXXX710f5388a27fee

Security Scheme Type:

apiKey

Header parameter name:

X-Auth

Contact

SignageOS Support:

URL: https://docs.signageos.io