The Vidispine API is a REST API, using HTTP as a transfer protocol.
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
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 list of items/jobs or storage definition etc.
- Does not change anything to the database.
- Start jobs, create new collection, etc.
- Will create one or more new entities in the database.
- Update existing entity, create new entity with supplied id.
- Identical sequential requests will not create new entities.
- Delete items, abort jobs, etc.
- Identical sequential requests will not change anything (fails gracefully on subsequent requests).
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 are given as query parameters or header parameters.
Given at the end of the URI. The query parameters follows after a question
?), and each query parameter key/value pair is delimited by an
&). An equal sign
= is used to separate key and value.
Keys and values have to be URL encoded.
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).