Introduction
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.
| 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.