Versions Compared

Old Version 25

changes.mady.by.user BrightSign TechDocs

Saved on

compared with

New Version Current

changes.mady.by.user BrightSign TechDocs

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: updated format

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.

The BrightSign REST API This documentation describes request /and response entities using JSON examples and data types (integer, string, array, etc.).. See 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 for more information.

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.

Authentication Workflow

The BrightSignNetwork.com authentication process uses access credentials to produce a token which is then used to control access to all BrightSignNetwork.com resources in your network.

The authentication workflow is based on the OAuth2 protocol (rfc6749). The BSN user model distinguishes between "persons" and "users":

  • A "person" is tied to a single set of login credentials, but is not exclusively linked to any one network (each network is an independent set of users, files, presentations, etc.).
  • A "user" is an instance of a person that is associated with a single network.

This user model allows persons who belong to multiple networks to log in to them using a single set of credentials. In many cases, it also requires two token-authentication requests, as described below.


Panel
borderColor#3D3D3D
bgColor#F4F4F4
titleColor#3D3D3D
borderWidth0
titleBGColor#3D3D3D
borderStylesolid

ON THIS PAGE

Table of Contents
maxLevel43
indent20px


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 To authorize a client application:

Authorization

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

Filter Expressions  Anchorfilter_expressionsfilter_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".

Code Block
languagexml
titleExample (single operator)
GET /2017/01/REST/Content/?filter=[mediaType]%20IS%20'video' 
Code Block
languagejs
titleExample (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
titleNote

 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
titleNote

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
titleNote
Leading and trailing spaces aren't valid in BrightSign entity names
  1. Make a POST call to the /token endpoint which includes a username and password. You can enter the network name with the username (for example, 
/Presentations/ ). Query strings that are appended to endpoint URLs (for example, "?filter", "?sort") must be URL encoded.
  1. exampleNetwork/exampleUser@brightsign.biz). If  you do not, a network must be specified in step 2.
  2. If the credentials are valid, the server returns code 200 with a response body that includes access_token, expires_in, and refresh_token values. If a network name was not specified, the response will include the networks associated with the username. Select a network, which will be included in the username in the next POST call.
  3. If less than half of the expires_in time has elapsed and the client application has retained the access_token value in local storage, it includes the access_token in the "Authorization" header of each request to a BSN endpoint. The value of the "Authorization" header is specified as "Bearer {token_value}".
    • If more than half of the expires_in time has elapsed, or if the access_token is not located in local storage, the client application will  make a POST call to the /token endpoint with the refresh_token value.
    • If the refresh_token is not located in local storage, or if the expires_in time has elapsed (indicated by a 401 return from the server), the application will indicate that access to the BSN connection has been dropped (without loss of unsaved user data) and prompt you to reenter access credentials and returns to step 1 of the authentication process.
    • The expires_in value may be changed on the server at any time, or it may be randomized on each authentication return. Therefore, the token expiration time should not be hardcoded on the client application; the application should store the expires_in value along with the Access/Refresh token and calculate a new token-refresh interval on every return.


/Token

POST

Posts user credentials or a refresh token to the /Token endpoint (this endpoint does not accept a trailing slash). If the credentials are valid, the server returns an access/refresh token that is included with all other BSN REST calls for authentication.

Request Body

username: The BrightSignNetwork.com username. A network name can be appended (for example, exampleNetwork/exampleUser@brightsign.biz).

password: The password associated with the username.

network: The network to which the returned token should grant access. This entry can can be used for either the initial authentication request, or to switch to another network that the user belongs to on token renewal.

grant_type: The type of grant being presented in exchange for the access token. This value must be set to "password".

client_id: The client identifier. This value is currently not used by the server.

client_secret: The client secret. This value is currently not used by the server.

refresh_token: The refresh token to include when renewing the access token. When the refresh_token entry is included, the password does not need to be used.

Response Body

access_token  string: The authorization token to use with endpoint calls until half of the expires_in time period has elapsed

token_type string: The OAuth 2.0 token type, which will always be returned as "bearer"

expires_in integer: The lifetime (in seconds) of the authorization token

refresh_token  string: The token to use for re-authentication when more than half of the expires_in time period has elapsed.

scope  string[]: An array that lists the scope granted by the token. A successful Person Authentication Response will include the "Self" value only, while a successful User Authentication Response will contain both "Full" and "Self" values. 

userLogin string: The username included in the request body

userId  integer: The user identifier, which may be used in subsequent requests. This entry is only returned for User Authentication Requests.

personId integer: The person identifier

networkNames string[]: An array of networks to which the person (i.e. the account associated with the login credentials) belongs. This entry is only returned for Person Authentication requests.

.issued string: The date and time the authorization/refresh token was issued (formatted as "[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]")

.expires string: The date and time the authorization/refresh token expires (formatted as "[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]")

Person Authentication Examples

Request Body

The client application makes this authorization request when it does not have the network name. A successful response will include a list of network names.

Code Block
POST https://api.brightsignnetwork.com/2017/01/REST/token
Host: api.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 158
Accept: application/xml

grant_type=password&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&username=exampleUser@brightsign.biz&password=admin&scope=self

Response Body

A successful response will include a HTTP status code of 200. Note that the response includes the networkNames list.

Code Block
{
"access_token":"N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"ee6c055a441047e99e5e2c3dde63fa4c",
"scope":"Self",
"userLogin":"exampleUser@brightsign.biz",
"personId":13898,
"networkNames":"AuthenticationTest1,AuthenticationTest2,AuthenticationTest3",
".issued":"Fri, 03 Feb 2017 23:02:00 GMT",
".expires":"Fri, 03 Feb 2017 23:17:00 GMT"
}

If the credentials are not valid, the server will return code 400 with the following response body:

  • error: Returns the error status (for example, "invalid_request" or "invalid_grant")
  • error_description: A description of the error (for example, "The specified Username or Password is incorrect")

User Authentication Examples

Request Body

The client application makes this authorization request when it has the network name, which can be retrieved either from user entry or from a Person Authentication Request. Note that the response body includes the roleName parameter, which allows the client application to determine the permissions scope and available functionality for the user.

Code Block
POST https://api.brightsignnetwork.com/2017/01/REST/token
Host: api.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 178
Accept: application/xml

grant_type=password&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&username=AuthenticationTest1/exampleUser@brightsign.biz&password=admin&scope=full

Response Body

A successful response will include a HTTP status code of 200.

Code Block
{
"access_token":"N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"375671af51fa44fabb5b4a353d4f8488",
"scope":"Full,Self",
"networkName":"AuthenticationTest1",
"userLogin":"exampleUser@brightsign.biz",
"userId":18537,
"personId":13898,
"roleName":"Administrators",
".issued":"Fri, 03 Feb 2017 23:37:26 GMT",
".expires":"Fri, 03 Feb 2017 23:52:26 GMT"
}

If the credentials are not valid, the server will return code 400 with the following response body:

  • error: Returns the error status (for example, "invalid_request" or "invalid_grant")
  • error_description: A description of the error (for example, "The specified Username or Password is incorrect")

Renew Access Token Examples

Request Body

Code Block
POST https://api.brightsignnetwork.com/2017/01/REST/token
Host: api.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 151
Accept: application/xml

grant_type=refresh_token&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&refresh_token=375671af51fa44fabb5b4a353d4f8488

Response Body

A successful response will include a HTTP status code of 200. 

Code Block
{
"access_token":"N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"375671af51fa44fabb5b4a353d4f8488",
"scope":"Full,Self",
"networkName":"AuthenticationTest1",
"userLogin":"exampleUser@brightsign.biz",
"userId":18537,
"personId":13898,
"roleName":"Administrators",
".expires":"Sat, 04 Feb 2017 00:05:26 GMT",
".issued":"Fri, 03 Feb 2017 23:50:26 GMT"
}

If the credentials are not valid, the server will return code 400 with the following response body:

  • error: Returns the error status (for example, "invalid_request" or "invalid_grant")
  • error_description: A description of the error (for example, "The specified Username or Password is incorrect")

Example API Call with Authorization

The access token is included in the "Authorization" header of each API request. The token value is prefixed with the "Bearer" specification.

Code Block
GET https://api.brightsignnetwork.com/2017/01/REST/Devices/ HTTP/1.1
Accept-Encoding: gzip,deflate
Origin: https://localhost/
Authorization: Bearer 79ADEgjjEOpSOsgQ1kpqYL0O3R8vnh27q22ltp7hyTgTQPWxdjrHD
Host: api.brightsignnetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)



Filtering Expressions 
Anchor
filter_expressions
filter_expressions

See Filtering Expressions in the Main API (2017/01)

Upload Endpoints

See Upload Endpoints for more information about how to upload files to BrightSignNetwork.com.