Qodex.ai

signageOS REST API Production

Number of APIs: 214

Introduction

signageOS helps any developer to build apps for displays and remotely manage large networks of displays in a standardized way. No matter what display you are using, all APIs work across all of them.

Read more here:


About REST API

The signageOS REST API brings extra features for signageOS users with out-of-the-box device management, monitoring, and maintenance service provided by signageOS. With an existing, scalable, and flexible solution you can easily integrate advanced features into your CMS via standardized REST API. No need to re-invent the wheel again.

All APIs are standardized and available across all supported devices.

To use REST API, you need an Organization on Device Plan 1.0, 2.0 or 3.0. REST API does not work on free Open Device Plan.


List of REST API Domains

DomainDescription
DeviceConfigure the device, set timers, brightness, volume, RM server url, update the Core App, update firmware and much more, get device uptime, temperature, outages, content status or custom logs.
AppletWay to create your own Applets and its versions over API instead of Box.
TimingTiming REST API helps you schedule Applets (your HTML player) on the devices.
OrganizationsOrganization/User REST API helps you to manage your account and create/delete organizations and retrieve security tokens.
AccountManage or delete security account tokens.
FirmwareManage firmware versions on supported devices.
EmulatorCreate emulators, test your environment or simply manage them.
PolicyManage policies with various settings, set up new policies or configure exiting policies and assign them to devices.
TagManage tags.
Alert(Coming soon) Manage device alerts and get informed about anomalies on production devices.
Location(Coming soon) Managing and filtering devices by assigned locations.
Bulk ProvisioningRegister your devices and automate the deployment


REST API Authentication

For REST API your application needs to be authenticated using request Header: X-Auth which is different for every single organization (end company owning/using devices). There is a possibility to create a sub-organization for any of your customers in signageOS Box.

  1. Go to Organizations section in signageOS Box and generate your tokenid & tokensecret.
  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

If X-Auth token is invalid or generated token does not have permissions in organization you will receive 403 Forbidden response.


REST API Request Quota

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.

It is important to note that after creating a Company through REST API, the default Device plan is set to 3.0. This can be changed from within SignageOS Box under your Company profile.


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. 1. The server accepts the request, confirming by 200 OK message. 1. 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. 1. 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: json { "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.


  1. Package-Version - Unpublish Package Version PUT {{baseUrl}}/v1/package/:packageUid/version/:packageVersionUid/unpublish

  2. Account - Create Account Security Token POST {{baseUrl}}/v1/account/security-token?identification=<string>&password=<string>

  3. Account - Delete All Account Security Tokens DELETE {{baseUrl}}/v1/account/security-token?identification=<string>&password=<string>

  4. Account - Delete One Account Security Token DELETE {{baseUrl}}/v1/account/security-token/:token?identification=<string>&password=<string>

  5. Applet - Get Applets GET {{baseUrl}}/v1/applet

  6. Applet - Get Applet Version File GET {{baseUrl}}/v1/applet/:appletUid/version/:appletVersion/file/:appletFileName

  7. Alert-Rule - Create Alert Rule POST {{baseUrl}}/v1/alert-rule

  8. Alert-Rule - Update Alert Rule PUT {{baseUrl}}/v1/alert-rule/:alertRuleUid

  9. BulkProvisioning-Recipe - Get Provision recipes GET {{baseUrl}}/v1/bulk-provisioning/recipe?limit=<number>&descending=true&search=<string>&status=Applied&brand=<string>&tagUids=<string>&tagUids=<string>&policyUids=<string>&policyUids=<string>&locationUid=<string>&model=<string>&macAddress=<string>

  10. Device-Debug - Get Device Debug GET {{baseUrl}}/v1/device/:deviceUid/debug