Overview: Delivery System API
Files associated with the Delivery System are managed through REST APIs, and optionally through Git. These files are delivered to players.brightcove.net either through an API call or a "git push".
If you haven't gone through the Step-by-Step: Delivery System API, it's highly suggested you start there. You'll get security set up, learn some of the basics of the system, and then be ready to dive in further here.
Also see the API Reference.
Delivery System REST APIs
The delivery system APIs are centered around repositories, otherwise known as repos. You can manage repos through a group of REST APIs that allow you to add, get, and list your repos. You can also use REST API calls to manipulate files in repos.
You can use the command-line tool curl to use the REST APIs. The REST APIs return responses in JSON format containing the following information on success:
- name: The repo name. This is the same as the name found in the REST API URLs.
- public_url: The base URL where the repo files can be seen.
The Step-by-Step: Delivery System provides a hands-on guide to using the Delivery System APIs.
You can authorize yourself using either OAuth access tokens or through Basic Authentication using your Brightcove username and password. The standard OAuth access tokens should be used for any programmatic usage of the APIs, but the Basic Authentication route is a lot easier for command-line usage and getting started.
We'll use Basic Authentication in the Step-by-Step examples. If you wanted to use access tokens instead, change:
--header "Authorization: Bearer $ACCESS_TOKEN"
API Error responses
There are a number of possible error responses that can returned in JSON format when there's an issue with a REST API call:
- If you try to call an API which does not exist, including misspelling existing API calls, you will get a status code of 404 and a helpful message about what you may have done wrong.
- If your call can not be authenticated or authorized, you will get a 403 status code. Try going over the OAuth guide again to ensure you have a valid access token.
- If you try to use a method other than GET or PUT, the response will contain a 405 status code.
- If there's a problem with processing your request, you'll get a 500 status code and a standard Brightcove error response.
The standard Brightcove error response mentioned above is a JSON response containing error_code and message properties. The error code will be one of the following:
INVALID_LOGIN_CREDENTIALS: the username and password given when using Basic Authentication were not valid
ACCESS_TOKEN_ERROR: the access token given was not valid
INVALID_API_CALL: the API call was not formatted properly
NOT_FOUND: the API call was not pointing to a known resource or was not formatted properly
NO_PUT_CONTENTS: A multi-part form with a contents key must be used to PUT a repo file
CREATE_REPO_ERROR: an error occurred while creating a repo
GET_REPO_ERROR: an error occurred while getting a repo
GET_REPOS_ERROR: an error occurred while getting all repos
UNCAUGHT_ERROR: an uncaught error caused things to fail
UNKNOWN_ERROR: an error which doesn't have an associated error code has happened