SAPI Characteristics


The Sapi API is reachable via your publication base URL. This usually is:

YOURPUBLICATION.bbvms.com where YOURPUBLICATION is the name of your publication.

1.0 | Object structure

Sapi CRUD uses a standardised object structure for all media objects:

  • Type property: determines the object type (e.g. “Project” or “MediaClip”)
  • Id property: determines the unique id
  • Status: determines the current status. Depending on the use of an object (content or configuration) status can contain draft/published (content) or active/inactive(configuration).
  • All endpoints are lower case versions of the object type: e.g. Mediaclip → /sapi/mediaclip.
  • Objects are expected and will be returned in JSON notation.
  • Dates are in ISO 8601 format and use the Zulu (UTC) timezone.

2.0 | HTTP status codes and method handling

  • Standard HTTP methods are used for all supported actions:
    • GET /sapi/ENDPOINT/ID gets an object.
    • GET /sapi/ENDPOINT does a “list view” or search on the given object type.
    • DELETE /sapi/ENDPOINT/ID deletes an object.
    • PUT/POST /sapi/ENDPOINT or PUT/POST /sapi/ENDPOINT/ID creates or updates an object. The object itself should be posted in the payload (body) of the request.
  • API requests are designed to be stateless. No session is required. One time tokens can be used to sign/authorise requests.
  • Lists are typically contained in an “items” property.
  • Responses consist of either the requested or updated object or a Response object (type: “Response”) containing information about the executed api request.
  • HTTP status codes follow the usual pattern:
    • 200 (OK) for a normal response
    • 204 (no data) for a pre-flight response
    • 404 (Not found) when the object is not available because it cannot be found (or is hidden because the status is “draft”
    • 403 (Forbidden) when the object is found but is not allowed to be returben or the request is denied for other reasons
    • 400 (Bad request) when the request is incomplete or otherwise invalid

3.0 | Metadata versioning and state management

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

GET /sapi/ENDPOINT/versions

Or when version metadata (e.g. Author) is required as well:

GET /sapi/ENDPOINT/ID/versions?metadata

Sapi will respond with a list of versions that might exist. To fetch an object in a certain version you can issue a: GET /sapi/ENDPOINT/ID/version/VERSION-ID

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

Updated on July 23, 2020

Was this article helpful?

Related Articles