Version 3.0 B-Deploy API Endpoints (old)

Owned by BrightSign TechDocs
Last updated: Apr 27, 2023
4 min read

These endpoints allow users to automatically provision BrightSign players over the internet. Version 3.0 of these APIs contains additional support for multiple network interfaces through the "Network" object, which returns an array of Network entities.

The two key updates in this version are:

  • The order of network interfaces indicating interface priority (cf. interface metric)
  • Forward compatible support for new and existing interfaces. The common interfaces are:

Endpoints:



See "Determine Network Interface Priorities" in Control Cloud API Integration Guide for more information

Base URL for these endpoints:  https://provision.bsn.cloud/rest-setup/v3/setup

_____________________________________________________________


GET  /

Returns a list of setup records in the exact format they are stored in the B-deploy database. The main setup values are stored in each array object in the “setupJson” parameter.

If you want to get information about a specific B-Deploy setup, see :_id/  GET

Query String Parameter

NetworkName string required

The user-defined name of the bsn.cloud network.


________________________________________________________

Example Request

curl --location 
	 --request GET 'https://provision.bsn.cloud/rest-setup/v3/setup?NetworkName=anon' \
	 --header 'Authorization: Bearer {{token}}'


Response

Success Response Body

200: Returns an array of the following information for each setup in the network:

_id string

The system-supplied id of the device setup


updatedAt string

A UTC timestamp indicating when the device setup was last modified.


createdAt string

A UTC timestamp indicating when the device setup was created.


username string

The bsn.cloud username


client string

The client id of the bsn.cloud server


packageName string

The client-defined name for the device setup package. This value must be unique among device setup packages that belong to your person entity.


setupType string

The device setup type (either "lfn", "sfn", "partner", "standalone", or "bsn")


version string

The B-Deploy cloud version. This value should be "3.0.0"


networkName  string

The BSN.cloud network name


deviceName string

The user-defined device name


deviceDescription string

The user-defined device description


bsnGroupName string

The bsn.cloud group name


setupJson DeviceSetup{}

A  Device Setup Entity (v3), which contains all of the setup parameters in stringified JSON

Failure

400: The request is malformed and therefore invalid (for example, "NetworkName" is not specified)

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method. The access token used to call this /v3/setup API must belong to the same network.

5XX: Any 500 code is an internal server error




POST  /

Adds device setups to the B-Deploy server

Request Body

The Device Setup Entity (v3)

________________________________________________________

Response

Success Response Body

201: The id of the device setup object

Failure

400: The request is malformed and therefore invalid (for example, "Package Name" is required)

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

415: The server cannot accept the data representation that you sent (as specified in the header)

5XX: Any 500 code is an internal server error

Example Request

curl --location 
	 --request POST 'https://provision.bsn.cloud/rest-setup/v3/setup?query%5BnetworkName%5D=Test' \
	 --header 'Content-Type: application/json' \
	 --header 'Authorization: Bearer {{token}}'\
	 --data-raw '{exampleDeviceSetupObject}'

Note that the data-raw flag allows a request body to be passed and exampleDeviceSetupObject is a placeholder for a device setup object.


PUT  /

Updates existing device setups on the B-Deploy server.

Request Body

_id string required

The database id of the device setup you want to update.


version string

The B-Deploy Cloud version. This value should be "3.0.0".


setupType string

The device setup type. This value is currently "bsn".


bsnGroupName string optional

The name of the BSN.cloud group to which provisioned devices will be assigned. This value defaults to the "Default" group if undefined.


url string optional

A value of the Partner Application URL specified for a device to use when finding the application to download.


bDeploy object

A B-Deploy Entity (v3)


bsnDeviceRegistrationTokenEntity object

A Token Entity (v3)


DeviceSetup object

A Device Setup Entity (v3)

________________________________________________________

Response

Success

200: The existing device setup has been updated

Failure

400: Either the request or request body is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

415: The server cannot accept the data representation that you sent (as specified in the header)

5XX: Any 500 code is an internal server error

Example Request

curl --location 
	 --request PUT 'http://player_ip/v3/setup?username=example@gmail.com' \
	 --header 'Content-Type: application/json' \
	 --header 'Authorization: Bearer {{token}}'\
	 --data-raw '{exampleDeviceSetupObject}'

The data-raw flag allows a request body to be passed and exampleDeviceSetupObject is a placeholder for a device setup object.


DELETE  /

Deletes a device setup from the B-Deploy server.

Query String Parameter

_id string required

The id of the device setup to delete

___________________________________________________


Response

Success

200: The specified device setup has been removed

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

5XX: Any 500 code is an internal server error

Example Request

curl --location 
	 --request DELETE 'https://provision.bsn.cloud/rest-setup/v3/setup/618fb7363a682fe7a40c73ca' \
	 --header 'Authorization: Bearer {{token}}'


GET  /:_id/ 

Retrieves the device setup from the B-Deploy server for one specified setup id. 

Query String Parameter

_id string required

The database id of the device setup you want to retrieve. This "id" is returned in the response to /rest-setup/v3/setup/POST, above.

________________________________________________________

Example Request

curl --location 
	 --request GET 'https://provision.bsn.cloud/rest-setup/v3/setup/618fb7363a682fe7a40c73ca' \
	 --header 'Authorization: Bearer {{token}}'


Response

Success Response Body

200: Returns an empty array of device setup errors and the  Device Setup Entity (v3)

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method. The access token used to call this /v3/setup API must belong to the same network.

5XX: Any 500 code is an internal server error