Get started with SAPI

SAPI is the “Server API” that can be used to manage, publish and retrieve content from (web) applications. The SAPI Reference Guide contains information about its general usage and authentication, as well as a list of supported endpoints and routes.

The SAPI is a RESTful API that uses JSON notation for most content representations. SAPI can be used through several publicly available REST clients. A basic PHP wrapper is available here.

1.0 | SAPI characteristics

The Server API is accessible by using your publication base URL. For example “my-beautiful-publication.bbvms.com” or “company-name.bbvms.com”.

1.1 | Object structure

• A standardised object structure is used for all media objects:
  • “type” property: object type (e.g. “project” or “mediaclip”)
  • “id” property: unique entity id
  • “status”: current status for content (draft/published) or configurations (active/inactive).

• All endpoints are lower case versions of the object type. For example:
  • Mediaclip: my-beautiful-publication.bbvms.com/sapi/mediaclip
  • Project: my-beautiful-publication.bbvms.com/sapi/project
  • Channel: my-beautiful-publication.bbvms.com/sapi/channel
  • Playout: my-beautiful-publication.bbvms.com/sapi/playout
• Objects are returned in JSON format.
• Dates are in ISO 8601 format and use the Zulu (UTC) timezone.

1.2 | HTTP methods (GET, DELETE, PUT, POST) 

• Standard HTTP methods are used for all supported actions:
  • GET /sapi/{endpoint}/{entity-id} retrieves an object.
    For example: GET my-beautiful-publication.bbvms.com/sapi/mediaclip/123456
  • GET /sapi/{endpoint} retrieves a list or search on the given object type.
    For example: GET my-beautiful-publication.bbvms.com/sapi/mediaclip
  • DELETE /sapi/{endpoint}/{entity-id} deletes an object.
    For example: DELETE my-beautiful-publication.bbvms.com/sapi/mediaclip/123456
  • PUT/POST /sapi/{endpoint} creates the object included in the payload (body) of the request.
    For example: POST my-beautiful-publication.bbvms.com/sapi/mediaclip
  • PUT/POST /sapi/{endpoint}/{entity-id} updates an object with the properties included in the payload (body) of the request.
    For example: PUT my-beautiful-publication.bbvms.com/sapi/mediaclip/123456
• API requests are designed to be stateless. No session is required. One time tokens can be used to sign/authorise requests.
• Responses consist of either the requested or updated object or a Response object (type: “Response”) containing information about the executed api request.

1.3 | HTTP status codes

HTTP status codes follow the usual pattern:

• 200 (ok): successful request
• 204 (no data): a pre-flight response.
• 400 (bad request): incomplete/invalid request. The server could not understand the request due to invalid syntax.
• 403 (forbidden): the client does not have authorized access to the object.
• 404 (not found): object cannot be found (or is hidden because the status is “draft”).

1.3 | Metadata versioning and state management

Most object types (endpoints) support metadata versioning and state management. Metadata versions can be retrieved by:

GET /sapi/{endpoint}/{entity-id}/versions
For example: GET my-beautiful-publication.bbvms.com/sapi/project/1234/versions

When the version “author” is required:

GET /sapi/{endpoint}/{entity-id}/versions?metadata
For example: GET my-beautiful-publication.bbvms.com/sapi/mediaclip/123456/versions?metadata

To retrieve a specific version:

GET /sapi/{endpoint}/{entity-id}/version/{version-id}
For example: GET my-beautiful-publication.bbvms.com/sapi/project/version/yRYi1fLkiumvZYm.qsrI1uILf1ayACNz

To PUT or GET an object in a specified state (e.g. “staging” or “work-in-progress”: include a “state” http header in the request. If the state is not found the default state will be used instead.

2.0 | Authentication

Authentication is required using time based tokens on a shared secret. As part of the onboarding process, you will receive a set of API key credentials. OVP users with admin access can also access these API key details in the publication settings (learn more about API key management).

The secret listed in the API key credentials can be used to calculate time-based tokens. SAPI uses the HOTP algorithm for token calculation.  Read more about HOTP here.

These are some platform specific examples:

var speakeasy = require("speakeasy");
var request = require('request'); 

var ROOT_SECRET_ID = 123; // Use "id" from API key credentials.
var ROOT_SECRET = "12345678f9e01dc2ba3e4d56c7b89ae0" // Use "secret" from API key credentials. 
 
var token = speakeasy.totp({ 
  secret: ROOT_SECRET, 
  digits: 10, 
  step: 120 
});
  
var url = "http://my-beautiful-publication.bbvms.com/sapi/publication?rpctoken=" + ROOT_SECRET_ID + "-" + token;
 
request.get( { 
    url : url 
  }, function(error, response, body) { 
      console.log('body : ', body); 
      console.log('response : ', response); 
  } );

123-1234567890