Main REST HTTP API version 2017/01

BrightSign API structures operations and services are based on the REST principles. This approach allows you to group your data by resources, and for each resource, define a list of operations. The REST style is commonly used for create, read, update, and delete (crud) operations.

This documentation describes request/response entities using JSON examples and data types (integer, string, array, etc.).

Basic Usage Rules and Conventions

Requests Must Be Complete

All the entities and structures sent to the server in the POST/PUT request body must be structurally complete. This means that they need to contain all documented properties regardless of whether their values are needed. Unknown and optional values may be specified as either "null" or "0" but needs to be specified explicitly to remove the need for the server to guess and fill them on its own. In response, the server also will always send complete structures so the client doesn't have to check the presence of each property before reading it.

HTTP Status Codes

The BSN REST API version 2017/01 may respond with the following HTTP status codes according to rfc7231: 100, 200, 201, 202, 204, 300, 304, 307, 308, 400, 401, 403, 404, 405, 406, 408, 411, 412, 413, 414, 415, 429, 431, 500, 502, 503, 504, or 505.

Request Values

The actual values in requests must strictly match the data types in the properties. Which data types are nullable and which are not should be clearly defined. See Data Types.

Data Request Structures

Each BSN REST API data request must contain the "Accept" HTTP header. Make sure that it lists only content representations that are really supported by the client. Values like "*" and "application*" are accepted but produce random result from the list of representations supported by the server, which also may change from time to time, according to rfc7231#section-3.4.

Each BSN REST API data request may also contain an "Accept-Encoding" HTTP header with the list of traffic compression algorithms supported by the client (for example, "gzip" or "deflate"), and expect either non-compressed or compressed by the algorithm specified in "Content-Encoding" HTTP response header according to rfc7231. All update/create requests should contain the "Content-Type" header.

All endpoints support the "application/json" and "application/xml" types, except for the /sessions/ endpoint, which uses a unique set of content types for file uploads.

Conditional Requests

BrightSign BSN REST APIs support conditional requests in all singular entity retrieval editing and removal methods (for example, PUT, DELETE, PATCH). You should use conditional requests when multiple retrievals of the same entity is expected and especially in update and delete requests of a single entity. They are implemented according to rfc2616 on the server side and based on the "Last-Modified", "If-Modified-Since" and "If-Unmodified-Since" HTTP headers.

Traffic Compression

Traffic compression for BSN REST API requests may also be implemented on demand but such case is not described in rfcStandards so may be based only on our agreements.

ON THIS PAGE

URLs and Endpoints

The base URL for the BrightSignNetwork.com Main REST API, version 2017/01, is https://api.brightsignnetwork.com/2017/01/REST/.

Endpoints are appended to this base URL. Except for the /Token endpoint, all BSN endpoints accept trailing slashes (for example, /Presentations/ ). Query strings that are appended to endpoint URLs (for example, "?filter", "?sort") must be URL encoded.

Authorization

All requests, except for those to the /token endpoint, must contain the "Authorization" header. See the Authentication page for more details.

Filter Expressions

GET calls that return multiple items accept the "?filter" query string, which allows the client to filter list returns according to one or more entity values. The query string can have multiple operators joined together with "AND" or "OR".

Example (single operator)

GET /2017/01/REST/Content/?filter=[mediaType]%20IS%20'video'

Example (multiple operators)

GET /2017/01/REST/Content/?filter=[fileName]%20BEGINS%20WITH%20'ex'%20AND%20[mediaType]%20IS%20'image'

Accepted expressions are described below.

String Operators

Note

String operators are case-insensitive.

[entry] IS '<value>': Returns items that contain the entry equalling <value>. This operation supports the "*" and "?" wildcards.
[entry] IS NOT '<value>': Returns items that do not contain the entry equalling <value>. This operation supports the "*" and "?" wildcards.
[entry] BEGINS WITH '<value>': Returns items that contain the entry starting with the <value> substring.
[entry] ENDS WITH '<value>': Returns items that contain the entry ending with the <value> substring.
[entry] CONTAINS '<value>': Returns items that contain the entry with the <value> substring.
[entry] DOES NOT CONTAIN '<value>': Returns items that do not contain the entry with the <value> substring".
[entry] CONTAINS ALL ('<value_1>', '<value_2>', [...]): Returns items that contain the entry with all of the specified substrings.
[entry] CONTAINS ANY ('<value_1>', '<value_2>', [...]): Returns items that contain the entry with any of the specified substrings.
[entry] IS IN ('<value_1>', '<value_2>', [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN ('<value_1>', '<value_2>', [...]): Returns items that do not contain the entry equalling any of the specified values.

Enumeration Operators

Some string-value entries are enumerations: For example, the [mediaType] entry on the Content endpoint can only have "Video", "Image", "Audio", "Text", and "Other" values. The following operators can be used with enumeration entries:

[entry] IS '<value>': Returns items that contain the entry equalling <value>.
[entry] IS NOT '<value>': Returns items that do not contain the entry equalling <value>.
[entry] IS IN ('<value_1>', '<value_2>', [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN ('<value_1>', '<value_2>', [...]): Returns items that do not contain the entry equalling any of the specified values.

Number Operators

[entry] IS <value>: Returns items that contain the entry equalling <value>.
[entry] IS NOT <value>: Returns items that do not contain the entry equalling <value>.
[entry] IS GREATER THAN <value>: Returns items that contain the entry with a value greater than <value>.
[entry] IS LESS THAN <value>: Returns items that contain the entry with a value less than <value>.
[entry] IS IN THE RANGE <value> AND <value>: Returns items that contain the entry with a value between the specified range.
[entry] IS NOT IN THE RANGE <value> AND <value>: Returns items that do not contain the entry with a value between the specified range.
[entry] IS IN (<value_1>, <value_2>, [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN (<value_1>, <value_2>, [...]): Returns items that do not contain the entry equalling any of the specified values.
GPS LOCATION ([latittude_entry] AND [longitude_entry]) IN (<latitude_value>, <longitude_value>, <distance_value>): Returns items that have coordinate entries within <distance_value> of the specified <latitude_value> and <longitude_value>.
GPS LOCATION ([latittude_entity] AND [longitude_entity]) NOT IN (<latitude_value>, <longitude_value>, <distance_value>): Returns items that do not have coordinate entries within <distance_value> of the specified <latitude_value> and <longitude_value>.

DateTime Operators

Note

DateTime values are formatted as yyyy-mm-ddThh:mm:ss.sssZ.

[entry] IS '<dateTime>': Returns items that contain the entry equalling <dateTime>.
[entry] IS NOT '<dateTime>': Returns items that do not contain the entry equalling <dateTime>.
[entry] IS AFTER '<dateTime>': Returns items that contain the entry with a time before <dateTime>.
[entry] IS BEFORE '<dateTime>': Returns items that contain the entry with a time after <dateTime>.
[entry] IN THE LAST (<units>, <length>, '<dateTime>'): Returns items that have a time entry within <length> before <dateTime>. The time <length> is quantified with the <units> parameter, which can have one of the following values: years, months, days.
[entry] NOT IN THE LAST (<units>, <length>, '<dateTime>'): Returns items that do not have a time entry within <length> before <dateTime>. The time <length> is quantified with the <units> parameter, which can have one of the following values: years, months, days.
[entry] IS IN THE RANGE '<dateTime>' AND '<dateTime>': Returns items that have a time entry that falls between the two <dateTime> values.
[entry] IS NOT IN THE RANGE '<dateTime>' AND '<dateTime>': Returns items that do not have a time entry that falls between the two <dateTime> values.
[entry] IS IN ('<dateTime_1>', '<dateTime_2>', [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN ('<dateTime_1>', '<dateTime_2>', [...]): Returns items that do not contain the entry equalling any of the specified values.

Boolean Operators

[entity] IS TRUE: Returns items that contain the entry equalling a true value.
[entity] IS FALSE: Returns items that contain the entry equalling a false value.

Note

Leading and trailing spaces aren't valid in BrightSign entity names.