Best Practices: CMS and Playback APIs

This topic provides best practices for using the Catalog APIs (CMS and Playback APIs).


Both the CMS and Playback APIs provide access to your Video Cloud video data. The purpose of this topic is to help you understand the difference between them and the best practices for using them.

Differences between the CMS and Playback APIs

The CMS and Playback APIs access the same underlying video data. There are some key differences between them that should determine which one you use in particular situations, however.

Generally speaking, the CMS API is intended for backend use, such as integrating Video Cloud with your CMS system. The Playback API is intended for frontend use to fetch video and playlist data for players or video portals (the Brightcove Player catalog and playlist APIs use the Playback API, for example).

The table below lists some key differences between the two APIs.

CMS vs Playback
Item CMS API Playback API
Kinds of operations create, read, update, delete read-only - no data can be modified using the Playback API
Scope of operations Manage every aspect of your video data Fetch specific videos or playlists, or search for videos
Authentication Temporary access tokens Permanent policy keys
Freshness of data No caching, always current Cached for up to 20 minutes
Speed of responses Slower Faster (because of the caching)
Access Server-side only (CORs disabled) Server or client-side (CORs enabled)
Data Video and playlist requests do not include video source URLs; a second request is required to get those Video and playlist requests do include video source URLs

Using Media URLs

It is important to understand that URLs for renditions, images, and other assets are not fixed. Brightcove reconfigures the storage of media assets from time to time, and when this happens, URLs for specific assets will change. If you are relying on hard-coded URLs to these assets in your pages or apps, the links will break at some point.

In addition, all URLs contain a TTL token for content security reasons. This means that the URLs expire after 6 hours by default. The life of the token can be extended up to 365 days - if you want longer-lived tokens, Contact Brightcove Support. Be aware, however, that the TTL reflects the maximum time that asset will be cached by the CDN, but is not a guarantee that the URL will not change before the token expires.

For VOD content, you can specify a shorter TTL on the manifest URL. For details, see the Short Manifest TTL document.

The best way to prevent links to media from breaking is to retrieve them from Video Cloud at runtime using the CMS API or the Playback API.

Caching URLs

Brightcove does NOT recommend having any cache in front of the Playback and CMS APIs.

Static URLs

Brightcove provides static URLs to video manifest files for assets in your Video Cloud library. This gives you the flexibility to manage your content in your own CMS, and deliver it using a custom security schema.

This is important for customers who have existing architecture that does not allow a Playback API call before needing the manifest url(s). The player can also use this feature, reducing playback start time by eliminating one call.

For details, see the Static URL Delivery document.

Short manifest TTL

In the playback workflow, the Brightcove Player calls the Playback API (or Edge Auth API) to retrieve the available manifests to start playback by providing a policy key (or JWT) for authentication.

A caching layer has been introduced to allow these APIs to scale and be highly available. That layer stores the responses from the Signed Manifest URL API and the Playback API. Since the signed manifests will be cached, the TTL must be long enough to be valid for the time in the cache, plus a buffer for the player to use.

Short manifest TTLs allow viewers to continue playback without hindrance. Also, all the Dynamic Delivery features work with Short manifest TTL.

Reference id conflicts

This section applies to the CMS API only.

To insure the uniqueness of reference ids, the CMS API locks the id for up to 3 minutes after any operation on the video it is assigned to. This can result in 409 errors being returned when you attempt to retry a request that fail too quickly, or when you try to reuse a reference id too soon after deleting the video it was previously assigned to. See the Error Message Reference for more details.