Using the Media Manager console? Click here for the Media Manager user guide

 

Overview

The Media Manager API is based on the PBS Core Data Model which improves the way stations, producers, and viewers of PBS.org search and view digital assets. This document is intended for developers who want to write applications that interact with the Media Manager API. It explains basic concepts of the Media Manager API and provides an overview of the different functions that the API supports.

Before you start using the API: 

  • Familiarize yourself with the core concepts of the JSON (JavaScript Object Notation) data format. JSON is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.
  • Familiarize yourself with the Basic Authentication HTTP Protocol. To use the API, Basic authentication will have to be used. You can find more details in the API Authentication section.

Access

At this time, the Media Manager API is intended for use by PBS producers and stations only. If you are a PBS station or producer, you can request an API key to get started.

Testing Environment

Want to test the API without affecting your live data? Use the following staging/testing base endpoint:

Staging environment base endpoint
https://media-staging.services.pbs.org/api/v1/

The staging environment requires a separate API key. Request an API key

Authentication

In order to access exposed resources, an API consumer needs to be assigned to a Group that is assigned to a specific Station. The protocol for authentication is Basic Auth as defined by the Internet Engineering Task Force, in the Request for Comments number 2617 (http://www.rfc-editor.org/rfc/rfc2617.txt). In order to use this API, Basic Auth protocol must be used. An API Consumer can execute various operations including reading data and modifying data.

What is an API Consumer?

Click here to obtain a key and secret

An API Consumer is defined by a key (example: john) and a secret (example: mypassword). The key and secret are similar to a username and password and both must be provided to users of the API.

For all supported HTTP request methods see the individual page for each resource . All requests must contain the header Authorization, which contains the name of the authentication method (Basic), followed by a base64 encoded string of type key:secret.

Example

For key = 'john' and secret = 'password' - Authorization: Basic = am9objpteXBhc3N3b3Jk

To obtain am9objpteXBhc3N3b3Jk, we took the string john:mypassword and used a tool like http://www.base64encode.org/ to encode it.

Who is permitted to access Media Manager API?

Only PBS stations and producers are permitted to have access to the Media Manager API. It is not available to the general public at this time.

How do I obtain authentication credentials?

If you are a PBS station or producer, you can obtain authentication credentials by filing a support ticket.

 

API Authorization

The authorization section handles configuration needed for the API consumer to have the right to access/ edit certain resources exposed by the private API.

In order for an API consumer to have access to the exposed resources, it needs to be assigned to a Group, who has a specific Station assigned.

For the resources that are currently exposed, namely the Station the Group that the consumer was assigned to, also needs to have assigned to it the Permission to change the specific resource (change the station currently).

(warning) This section may be revised to include changes as the API evolves.

 

HTTP Request Headers

At the moment we’re only accepting JSON and JSONAPI specific headers.

 

HeaderMeaningValue
Content-TypeThe content type of the payloadapplication/json
Content-TypeThe content type of the payloadapplication/vnd.api+json


HTTP Response Status Codes

The following are possible status codes returned by responses to the API calls.

 

Status codeMeaningResolution
200SuccessOperation was successful.
204No content.Operation was successful.
400Bad requestDescription of the error will be given in the payload.
401Unauthenticated consumerThe consumer with this key:secret pair doesn’t exist in the system.
403Unauthorized consumerThe consumer with the key:secret doesn’t have access to this resource.
404No resources foundThe demanded resources cannot be found.
409ConflictAccording to existing business logic, the request would cause a conflict and could not be carried out.
500Internal server errorUnknown error

Technical Details

  • AWS CloudFront
  • General: Django (latest), Python 3, PostgreSQL
  • Console: Themed Bootstrap framework shared by our other, newer consoles
  • Transcoding Service: AWS/Elemental
  • API: JSON, SSL + Basic Auth, Read / Write

Resources

A resource is an individual data entity with a unique identifier. View all resources