Have more questions? Submit a request

Getting started with REST APIs

  1. signageOS
  2. DevSpace Guides
  3. Manage devices using REST API

Introduction

This tutorial describes how to setup an Organization and a device via REST API. This tutorial covers the main sections including Applet creation and Timing settings.

The same steps can also be completed via signageOS Box:

  1. Getting Started Tutorial – Applet Creation Part 1
  2. Getting Started Tutorial – Applet Creation Part 2
  3. How to assign Applet to the device via Timings

Get User Token

The first task is to get the User Token which allows you to create the organization. Navigate and login to Box, then go to User Account section. With one User Token, you can create multiple organizations.

Within your user Settings section you will see the API security section, click Add new token:

api-tokens.pngpostman-header-location.png

Save the TOKEN_ID and TOKEN_SECRET for later use.

Create an Organization

Once you have your User Token, use the following REST API endpoint to create the organization. You can do that easily via Postman. 

Read on how to use Create Organization [POST]. Below is an example:

curl -X POST \
  https://api.signageos.io/v1/organization \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-auth: 423XXX29:22e8fXXX7f39' \
  -d 'name=Test-org2&title=Test-title2'

Make sure you have correctly set the x-auth Header, which consists of your __TOKEN_ID__:__TOKEN_SECRET__ from the above section.

As a response, you will get 200 and, in the Headers, the Location link to where to find your organization details.

Here you can see the Headers of the API response with the Location link:

postman-header-location.png

Navigate to the link returned in Headers under Location, do not forget to use the User's x-auth token:

{
   "uid": "117b6d8XXXX18ed4c",
   "name": "Test-org2",
   "title": "Test-title2",
   "createdAt": "2019-06-19T09:25:05.617Z"
}

Save the organization's uid for later use.

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

Get Organization Auth Tokens

You have now created your Organization, next get the Organization tokens from Create organization token [POST] API. For this API call you use the User Auth tokens for the last time.

curl -X POST \
  https://api.signageos.io/v1/organization/:orgUid/security-token \
  -H 'Cache-Control: no-cache' \
  -H 'x-auth: 423XXX29:22e8fXXX7f39' \

As a response you will get:

{
    "id": "7d22.....3543543",
    "securityToken": "c456b6af....0ac14e8",
    "name": "Your Token Name"
}

From this point on we will use the Organization tokens in the X-Auth Header - the Organization TOKEN_ID (id) and TOKEN_SECRET (securityToken) that was part of the above-mentioned API response.

Create an Applet

The next step is to create an Applet that will play your content. To do so, we will complete two steps:

  1. Creating a new Applet via Create Applet [POST] API
  2. Creating the first Applet version via Create Applet version [POST] API

1. Creating a brand new Applet

Now we are using Organization's Auth Token in the format token_id:token_secret.

curl -X POST \
  https://api.signageos.io/v1/applet \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-auth: 12a15XXX612d:2e220XXX7745' \
  -d '{
	"name":"My new Test applet"
}'

Check that the Applet was created in Box Applets and copy the Applet UID.

applet-uid.png

2. Creating the first Applet version

If you have your Applet code ready, use the following - Create Applet version [POST] - to create the first version of your Applet.

Put the content of your HTML file as a binary. For version is used SemVer format.

If you do not have your own applet yet, you can use one of our examples.

curl -X POST \
  https://api.signageos.io/v1/applet/fb9907ef5632eb857dda1b65b1dbbbb6fd2fe89d19324e9f6d/version \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-auth: 12a1XXX8612d:2e2201XXX77745' \
  -d '{
	 "binary": "<!doctype html>\n<html>\n\t<head>\n\t\t<title>McDonalds Demo</title>\n\t</head>\n\t<body> ......
     ......
     </body>\n</html>\n",
	 "version": "1.0.0",
	 "frontAppletVersion": "2.2.0"
}'

At this point we have succesfully created:

  • Organization
  • New Applet within the respective Organization
  • Pushed your code into the first Applet version

The next step is to set this Applet version 1.0.0 to the device.

Create a Device

For the purpose of this tutorial we will create an Emulator device by opening a new Chrome window (not in incognito) with the following URL: https://2.signageos.io/app/default/7.9.0/index.html?duid=YOUR_UNIQUE_ID

Please replace YOUR_UNIQUE_ID with some kind of hash like dk32fjs (numbers and letters only).

Within the Emulator window you will see the Verification hash. Use this hash to verify the device and assign it to the newly created Organization via the Set Device Verification [POST] API.

Now we are using Organization's Auth Token in the format token_id:token_secret.

curl -X POST \
  https://api.signageos.io/v1/device/verification \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-auth: 12aXXXX8612d:2e22XXXX7745' \
  -d '{
	"verificationHash":"cc5XXc"
}'

As a response you will get 200 and in Headers the Location link to where to find your device details including the device UID.

Set an Applet to Device via Timing

As the last step we set Applet version 1.0.0 to the newly created device. For this process, the Timing API exists in signageOS. It allows you to set specific version of Applet on the specific device - Create Timing [POST].

Important the API Call parameters:

  • deviceUid we get in previous step
  • appletUid of the newly created Applet
  • appletVersion in our case 1.0.0
  • x-auth is your Organization's Auth Token in the format token_id:token_secret.
curl -X POST \
  https://api.signageos.io/v1/timing \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-auth: 12a15XXX28612d:2e220XXX77745' \
  -d '{
	"deviceUid": "3ca8aXXXXbe589b",
	"appletUid": "ca21230XXXee88c",
	"appletVersion": "1.0.0",
	"startsAt": "2018-09-12T10:02:21.123",
	"endsAt": "2018-09-12T11:02:21.123",
	"configuration": { "identification": "d157bcd63a" },
	"position": 1,
	"finishEventType": "IDLE_TIMEOUT",
	"finishEventData": "DURATION"
}'

After this last step, you accomplished having the newly created Applet in version 1.0.0 assigned to the device.

Was this article helpful?
0 out of 0 found this helpful
Share