Overview: Delivery System API

In this topic you will get an overview of the Delivery System APIs, which allow for the management and deployment of a group of files, called a repository. This system was setup as a storage area for player related files, like the JavaScript and CSS files for custom built plugins.

Overview

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.

Authentication

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:

    --user $EMAIL

to:

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

Limitations