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