Overview

Media Types

The Carousel API supports the application/json media type, and all requests should contain an Accepts: application/json header. When performing a POST or PUT request, a Content-Type: application/json 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.

Partial 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 retreiving a bulletin that you intended to make changes to, you must use the GET/{id} endpoint to retreive a full record. Failure to retreive and send the full bulletin record when updating can cause loss of data.

You must use the GET/{id} endpoint when retreiving a bulletin to edit. Failure to PUT a complete bulletin record can result in loss of data.

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.

Cookie Based Authentication

The Carousel API will authenticate requests that contain a cookie linking the request to an active Frontdoor session. This authentication method should be used by applications that run along side the Carousel web 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 Frontdoor credentials. For more information on basic authentication, see: https://en.wikipedia.org/wiki/Basic_access_authentication.

Cross Origin Resource Sharing (CORS)

The Carousel API is configured, by default, 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. If modification is required, the CORS headers can be changed by editing the Web.config located in the CarouselAPI web directory on the Carousel server. Below is the default configuration for the CarouselAPI. For more on CORS, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS.

        <system.webServer>
            <httpProtocol>
                <customHeaders>
                    <add name="Access-Control-Allow-Origin" value="*" />
                    <add name="Access-Control-Allow-Methods" value="GET,HEAD"/>
                    <add name="Access-Control-Allow-Headers" value="Content-Type" />
                </customHeaders>
            </httpProtocol>
        </system.webServer>
        

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/ui/index. 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. For example, enter admin:trms to use the default credentials on a new Carousel system.