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:
Or when version metadata (e.g. Author) is required as well:
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.