Document toolboxDocument toolbox

Vidispine

RESTful API [VC 21.3.1 GEN]

Owned by Andreas Schmidt
Oct 05, 2021
2 min read

The Vidispine API is a REST API, using HTTP as a transfer protocol.

Some basics in the RESTful API

URI

The URI is used as a resource (noun). This means each entity in Vidispine has its own (base) URI. Example:

  • /API/item - All items

  • /API/item/VX-204 - A particular item

  • /API/item/VX-204/shape - All shapes for a particular item

  • /API/item/VX-204/shape/VX-576 - A particular shape for a particular item

Method

The HTTP method is used as a verb. The verb is used to specify whether to Create (POST), Read (GET), Update (PUT) or Delete (DELETE) an entity. This is called CRUD.

GET

  • Get list of items/jobs or storage definition etc.

  • Does not change anything to the database.

POST

  • Start jobs, create new collection, etc.

  • Will create one or more new entities in the database.

PUT

  • Update existing entity, create new entity with supplied id.

  • Identical sequential requests will not create new entities.

DELETE

  • Delete items, abort jobs, etc.

  • Identical sequential requests will not change anything (fails gracefully on subsequent requests).

Media type

Media types are important. To specify which media type the request has, HTTP header Content-type is used. To specify which media type the caller accepts as response, HTTP header Accept is used. Most methods in Vidispine read XML (application/xml) or JSON (application/json) and write XML or JSON. Some methods reads and/or writes text (text/plain), though.

Parameters

Parameters are given as query parameters or header parameters.

Query parameters

Given at the end of the URI. The query parameters follows after a question mark (?), and each query parameter key/value pair is delimited by an ampersand (&). An equal sign = is used to separate key and value. Keys and values have to be URL encoded.

Header parameters

Header parameters are given in addition to the URI. The Content-type and Accept headers have already been mentioned. Other header worth mentioning is the RunAs header used for authentication (Run-As option), and the index and size header, used at import (Import using the request body).