| Panel | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
ON THIS PAGE
|
The BrightSign Network SOAP API exposes a large set of BSN functionality using a standardized set of entities, methods, and properties. Developers can use this API to build new interfaces that have a different look and feel from, but provide a similar feature set to, the BrightSign Network WebUI.
Entities
Identifiers
Each entity has a unique ID consisting of an incremental integer value that functions as its Primary Key. This allows for simple identification and retrieval of a particular object instance. This value is usually not revealed to end users of the UI because it is only useful for internal client/server operations.
Some entities also have Alternate Keys (the [string] Name property, for example) because the system often requires the uniqueness of an entity within a BSN account. You can retrieve an entity using any of its keys, whether primary or alternate.
Dependency
Almost all entities have “parent” and “child” entities contained within a dependency tree: For example, a Dynamic Playlist entity includes Content entities on one hand, but is referenced by Presentation entities on the other. In this case, each Content entity is the “child” of the Dynamic Playlist entity, while each Presentation entity functions as the “parent” of the Dynamic Playlist entity.
If a particular object instance has one or more parent objects, then it is considered “in use”. In most cases, this status will affect the operations that can be performed with it.
Methods
The BSN Web API provides different methods to perform similar operations. It is possible, for example, to retrieve/update either all or a specified subgroup of properties. This allows you to choose which methods suit your deployment best in terms of usability, responsiveness, etc.
Entity Retrieval Methods
Currently, there are four types of entity retrieval method:
...
The BrightSign Network Web API implements a markers-based approach similar to the Amazon REST 3 API: The client specifies the marker (entity ID) of the starting element in the list, as well as the number of entities to receive. The server will indicate whether the response is truncated (i.e. there are more elements that can be retrieved by the next request) and provide the marker for the next object instance.
...
If a client has retrieved a first page and is in the process of retrieving the second while another client adds, updates, or removes two objects on different pages, the first client may receive an inconsistent state.
GetSpecified{EntityName(s)}
...
Methods of this type retrieve a single object instance using one of its Keys. Unlike other method types, these methods allow retrieval of child entities along with the requested entity. This behavior is useful for entity properties dialogues (e.g. a Group Properties dialogue that shows general information about a particular group) and entity management pages (e.g. a Dynamic Playlist management page that can be initialized with a single call).
Entity Update Methods
Currently, there are two types of entity update method:
...
These methods receive Entity IDs and one or more values for updating logically related properties within that entity (for example, changing the minimum required firmware values for a group). Methods of this type don’t require the client to retrieve the object first. This may be useful for small dialogs, groups of controls (such as those in BrightAuthor), or internal client logic for sealing off certain parts of functionality from end users.
Object Permissions
Currently, all supported entities have a predetermined set of Object Permissions that cannot be changed. Customizable permissions will be implemented in the future.
SOAP Endpoints
Currently, the BrightSign Network Web API consists of two web services with nearly identical configurations: the Application Service and the Content Upload Service. Each web service has two SOAP endpoints: One is configured to use the WS-* specification and the other to use the WS-I Basic Profile.
...
The WS-I Basic endpoint is defined for simple clients that support a small number of functions or don’t support the WS-* specification. This specification does not support sessions or transactions. It does not have its own security module, using IIS instead. As a result, the message format is much simpler. WS-I Basic is also supported by all languages and platforms; it is even possible to use it directly without a service reference (i.e. proxy class) if needed (for example, through JavaScript).
SOAP Access Point URLs
Use the following URLs to create service references:
...
The service-endpoint addresses are specified in the WSDLs. Most SOAP tools and libraries used to create references will find the addresses automatically. The current service endpoint URLs are as follows:
...
Each URL has a specified API version (e.g. “2014/04/”). API versions will rarely, if ever, change after production release, the exception being changes that will extend functionality but not affect existing clients. Older API version URLs may be removed at a later time if deemed obsolete.
User Authentication
Credentials
Both BSN endpoints use simple username-password authentication; the username has the following format: {AccountName/{UserLogin}. These credentials should be passed in the header of all SOAP requests according to the corresponding SOAP specification. The complex security rules of the WS-* endpoints are defined in the WS-Security specification. The WS-I Basic Profile, on the other hand, defines just two special elements in the message header for the username and password.
...
The WS-I Basic endpoint, on the other hand, is configured to use transport encoding, with message credentials exposed over HTTPS: Each request/response is sent to the web server or client in plaintext; it is then encoded and transferred over the Internet via SSL/TLS.
Development Tools
The BSN WebUI contains a simple method that can be used for configuration checks and client login dialogs:
...
This method validates the passed credentials and returns the corresponding User instance. Note that User credentials should be specified in all other method calls.