RESTful API [VC 21.3.1 GEN]

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