Authentication

All endpoints that create, update, or delete records as well as endpoints that allow reading sensitive methods require authentication. If no authentication is provided, the request will error with a 401 un-authorized status code. Authorization can be provided in two ways, described below.

Bearer Token Authentication

The Carousel API will authenticate requests that contain a Bearer Token linking the request to an active OAuth2 access token. This authentication method is only used by the Carousel user interface. All other applications should use HTTP Basic Authentication described next.

HTTP Basic Authentication

The Carousel API will authenticate requests that provide a valid Authorization header using valid credentials. For more information on basic authentication, see: https://en.wikipedia.org/wiki/Basic_access_authentication.

Overview

Media Types

The Carousel API supports the application/json media type, and all requests with the exception of requests made to /auth should contain an Accepts: application/json header. When performing a POST or PUT request, a Content-Type: application/json should also be sent.

All requests made to /auth should contain an Accepts: application/json header. When performing a POST or PUT request, a Content-Type: application/x-www-form-urlencoded should also be sent.

Response Structure

All JSON responses will contain a root object that contains the object being returned. Similarly, all requests are expected to contain a root object. See the section on API Requests & Live Testing for more details on JSON payloads.

Required Data for Updates

All endpoints require the full model structure when updating records. The Carousel API does not support PATCH requests and values marked as 'optional' will be treated as falsey or not set if not included in the payload.

Getting All Zone Specific Content

Zone specific models like Bulletins, Media and Templates require you to specify a ZoneID as a query param in the GET request for performance reasons.

Creating and Updating Bulletins

Creating a Bulletin from a template

Because bulletins and templates share an almost identical content structure it is quite easy to use the properties of a template to create a new bulletin. You only need to add the additional scheduling and group information. Newly created bulletins will appear at the end of the list of bulletins on a player.

Bulletin Status

With the exception of the value Saved, all bulletins statuses are determined by the Carousel API based on settings like the bulletin's schedule, dynamic content, and the user's ability to publish content.

Bulletin Grouping

Every bulletin in Carousel is part of a group. When creating a new bulletin its important to create the group first and then create the bulletin with the GroupID properly referenced.

Bulletin (Group) Ordering

The OrderEntries endpoint is used to GET and PUT the order for groups and their bulletins. Since every bulletin is part of a group, the endpoint returns an array of group references and each group reference contains and array of bulletin IDs. The order of the items in each array is what determines the bulletin order for the zone and it must be put back in its entirety. The Order key is a read only value.

Partial Bulletin Records

For performance reasons, using the GET all bulletins endpoint returns a partial bulletin record that has a minimal set of data. These objects will have a PartialBulletin property set to True. It is important when retrieving a bulletin that you intended to make changes to, you must use the GET/{id} endpoint to retrieve a full record. Failure to retrieve and send the full bulletin record when updating can cause loss of data.

Cross Origin Resource Sharing (CORS)

The Carousel API is configured to allow Cross Origin Resource Sharing among all domains for read only GET requests. This will allow the Carousel API to be accessed via Javascript from modern web browsers. For more on CORS, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS.

Versioning Compatibility

There are two version numbers when interacting with the Carousel API.

The first version number is the Carousel version number which can be obtained programmatically using the SystemInfo endpoint. This version number can be used to ensure that the Carousel server is compatible with the version required. It is recommended that clients confirm the Carousel version required when accessing the Carousel API.

The second version number is the Carousel API version which is currently v1. The Carousel API version will only be incremented if breaking changes are introduced to the API, meaning that an endpoint or model property has changed or been removed. Additions to the API, including new endpoints, models, or properties do not cause an increment in the API version. Therefore, it is important that clients be resilient to additional properties in request payloads. It is recommended to only rely on properties needed by the client application, not exact schemas.

When a breaking changed is introduced to the Carousel API, necessitating a new Carousel API version, the depreciated endpoints will still be made available for at least one Carousel release cycle. During this time, the depreciated endpoints will include an additional Warning header indicating the endpoint has been deprecated. It is recommended that clients monitor for the Warning header and alert users for the need to update the client.

Performance Considerations

For performance reasons certain API end points such as Media GET/, Bulletins GET/ and Templates GET/ require the user to specify a ZoneID query parameter when attempting to retrieve All items.

If no ZoneID query parameter is specified these requests will return a Unprocessable Entity (422) status code.

Testing

API Requests & Live Testing

The Carousel API comes with Swagger for testing the API. The Swagger interface can be found at /CarouselAPI/swagger. To test authenticated endpoints, enter a valid username and password seperated by a colon in the api_key input field at the top of the page. Click Explore to activate these credentials.