RESTful API

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, matrix 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.

Matrix parameters

Matrix parameters are be applied to the segments of the path of the URI. The are used to discriminate or modify the result. Before each matrix parameter key/value pair there should be a semicolon (;). Equal signs are used to separate key and value, and they have to be URL encoded.

In Vidispine, most of the times, the matrix parameters should be applied to the last segment, but before any query parameters.

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).