Application Programming Interface (API)

Authentication

All API requests must include a valid session ID in a cookie or an authentication header matching
the credentials of a user using basic HTTP authentication.

The session ID cookie will be automatically used if you have signed into the admin interface and are using the same web browser
to make API requests.

Restful API

The following endpoints are enabled for restful communications:

• /rest-api/screen
• /rest-api/screen/[SCREEN-ID]
• /rest-api/sequence
• /rest-api/sequence/[SEQUENCE-ID]
• /rest-api/libraryitem
• /rest-api/sequence/[LIBRARY_ITEM-ID]
• /rest-api/user
• /rest-api/sequence/[USER-ID]
• /rest-api/group
• /rest-api/sequence/[GROUP-ID]
• /rest-api/serverconfig
• /rest-api/serverconfig/[SERVER_CONFIG-ID]

Generic Object Structure

All objects follow a common basic structure.

{
    "id": "ABCEF1234567",
    "data": {
        "label": "My label",
        "version": "23",
        "createdMillis": "1404910684273",
        "modifiedMillis": "1412943312770",
    },
}

The id field is used to uniquely store and reference the object. The data field references an inner
object containing a map of name value pairs. Anything can be stored in this map and used in condition evaluation and for other purposes.
All values in the data must be text strings, however, they will be dynamically cast to numbers and boolean values when condition
evaluation is performed.

The data usually contains a label, a version number and two timestamps. Additional fields will vary depending on the object type.

Quick Data API

The following endpoints can be used for quickly making changes to data in objects. The purpose of this API is to
automate adding data that is used in stack item evaluation.

Data can be sent as a URL encoded form post or as query parameters in the URL. For example:

The Quick Data API can also be used to make data changes that are not part of stack item evaluation. For example quickly changing the sequence
being displayed or updating scrolling text on a screen. Changes take effect instantly.

To remove data from an object, provide the name and equals with no value.

Players can periodically connect to a web server and fetch a JSON object. The data in the JSON object will be used when evaluating
conditions.

For example, a web server on a train could be configured to return the next station and arrival time:

{
    "nextStation": "London Bridge",
    "eta": 4
}

A condition (in a stack item or event trigger) could use this data to display an item, another sequence or trigger a custom action:

nextStation == "London Bridge" && eta < 5

The reporting API is used to stream large reports and collected data for further analysis.

Click the download button in the interface to download a report.
Reports can be extemely large and the total size of the report is not known because it streamed directly out of the database.

To download a report via API use the following endpoints:

Display Report

Custom date ranges can be specified using startMillis and endMillis parameters. (Milliseconds
since the epoc)

A report for a specific screen can be downloaded by setting the screenId parameter.

The sequenceId and itemId parameters can be used for specific sequences and stack items.

Collected Data Report

All images, videos and other resources are named based on their raw data.
The Blob naming convention provides efficient storage, avoids data duplication, provides the ability to verify data and safely share
the data between local devices with strong consistency.

A Blob name is the MD5 of the binary data followed by a dash then the length in bytes.

For example: 962B5B1AF8C3B868D87979E92D8BFCE7-164197

A Blob can be cached forever because a Blob with a given name never changes.

Dynamic content uses snapshots. A snapshot is the dynamically generated Blob at a specific point in time.
Snapshots are updated after they are used in a lazy fashion.

Blobstores can be shared with multiple servers and served using a content delivery network (CDN).

For example: https://blobstore.net/962B5B1AF8C3B868D87979E92D8BFCE7-164197

Additional Blobstores

In addition to the global blobstore, additional blobstores can be specified in a cloud config.
This makes it possible for a digital signage network to use their own infrastructure for storing and distributing images and videos.

When configured, all new data uploaded will be transferred to one or more additional servers. Players will download using HTTP from the configured endpoints.

Uploading to custom S3 bucket

Uploading to custom blobstore

Uploading to custom server using FTP

Uploading to custom server using SCP

After adding a new blobstore configuration, test it by uploading content.

Multiple blobstores can be specified by using numbered name suffixes. For example blobstoreConfig_0=..., blobstoreConfig_1=..., blobstoreConfig_3=....
The blobstores must share the same HTTP endpoints (Round Robin DNS).

A newly configured blobstore can be primed using the /blobstore-sync tool.
This tool requires a user ID. All blobs accessible to the user will be transferred.

DS Loader provides a platform for loading software. Usually this will be a digital signage player but can potentially
be anything.

Custom players for the Android platform must implement the following methods:

• void start(Context context)
• void setLoaderData(Map<String, String> data)

The Context is an Activity or a DreamService. The
custom player must call setContentView(View v) in the Context to draw to the screen.

The method setLoaderData()<String, String> data) receives data and commands from the loader e.g. URL to download sequence data etc.

The loader control communications is designed to instigate secondary communications mechanisms
such as JSON data transfer over HTTP. The virtual persistent UDP connection enables the server to instantly send messages to
DS Loader and (indirectly) to player software at any time.

To add additional software to the list of players in the interface the following data must be added to a cloud config