Libraries¶
A library can be seen as a lightweight collection that is deleted on a regular basis if it is not being used. Libraries can only contain items.
Managing libraries¶
Retrieve a list of all libraries¶
- GET /library¶
Retrieves a list of the ids of all known libraries.
Matrix Parameters: - autoRefresh –
Optional boolean value, only list libraries with the specified auto refresh status.
New in version 4.2.3.
- frequencyFrom –
Optional integer value, only list libraries whose update frequency is greater than it.
New in version 4.2.3.
- frequencyTo –
Optional boolean value, only list libraries whose update frequency is less than it.
New in version 4.2.3.
- updateMode –
Optional string value, only list libraries with the specified update mode.
New in version 4.2.3.
Produces: - application/xml, application/json – URIListDocument containing the ids of all the libraries.
Role: _library_read
- autoRefresh –
Example¶
GET /library
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<uri>VX*48</uri>
<uri>VX*49</uri>
<uri>VX*45</uri>
</URIListDocument>
Create a library¶
- POST /library¶
Creates a library and returns the id of the created library.
Accepts: - application/xml, application/json – ItemListDocument that contains the ids of any items that should be added to the library
Produces: - application/xml, application/json – URIListDocument containing the id of the created library.
Role: _library_write
Example¶
POST /library
Content-Type: application/xml
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<item id="VX-250"/>
<item id="VX-1000"/>
</ItemListDocument>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<uri>VX*48</uri>
</URIListDocument>
Delete a library¶
- DELETE /library/(library-id)¶
Deletes the library with the specified id.
Produces: - application/xml, application/json – JobDocument containing library delete job.
Role: _library_write
Example¶
DELETE /library/VX*51
Library settings¶
Retrieve library settings¶
- GET /library/(library-id)/settings¶
Retrieves the settings and status of a library.
Produces: - application/xml, application/json – LibrarySettingsDocument
Role: _library_read
Example¶
GET /library/VX*67/settings HTTP/1.1
<LibrarySettingsDocument>
<id>VX*67</id>
<username>admin</username>
<updateMode>REPLACE</updateMode>
<autoRefresh>true</autoRefresh>
<query>
<field>
<name>originalWidth</name>
<range>
<value>640</value>
<value>720</value>
</range>
</field>
</query>
</LibrarySettingsDocument>
Update library settings¶
New in version 4.0.3.
- PUT /library/(library-id)/settings¶
Update the settings of a library.
Accepts: - application/xml, application/json – LibrarySettingsDocument
Role: _library_write
Library content¶
Retrieve library content¶
- GET /library/(library-id)¶
Returns the items together with any requested data.
Query Parameters: - content – See Retrieving item information
- noauth-url – Whether to return thumbnail URLs not requiring authentication. Default value is false
- baseURI – Which base URI to use for the thumbnail URLs.
Matrix Parameters: - starttc –
- true - Interval is given relative to start timecode of item.
- false (default) - Interval is 0-based.
- first – Integer, from resulting list of items, start return list from specified offset. Default is 1, start return list from beginning.
- number – Integer, set a limit on maximum number of hits. Default 100.
Produces: - application/xml, application/json – ItemListDocument containing the items together with the requested data.
Role: _library_read
Example¶
GET /library/VX*48/?content=access HTTP/1.1
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<item id="VX-250">
<access>
<type>GENERIC</type>
<permission>ALL</permission>
</access>
<access>
<type>METADATA</type>
<permission>ALL</permission>
</access>
<access>
<type>ID</type>
<permission>ALL</permission>
</access>
<access>
<type>URI</type>
<permission>ALL</permission>
</access>
</item>
<item id="VX-1000">
<access>
<type>GENERIC</type>
<permission>ALL</permission>
</access>
<access>
<type>METADATA</type>
<permission>ALL</permission>
</access>
<access>
<type>ID</type>
<permission>ALL</permission>
</access>
<access>
<type>URI</type>
<permission>ALL</permission>
</access>
</item>
</ItemListDocument>
Add multiple items to a library¶
- PUT /library/(library-id)¶
Adds all the items specified in the document to the library.
Accepts: - application/xml, application/json – ItemListDocument that contains the item ids.
Role: _library_write
Example¶
PUT /library/VX*48
Content-Type: application/xml
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<item id="VX-1000"/>
<item id="VX-250"/>
</ItemListDocument>
200 OK
Add a specific item to a library¶
- PUT /library/(library-id)/(item-id)¶
Adds the specified item to the library.
Role: _library_write
Remove a specific item from a library¶
- DELETE /library/(library-id)/(item-id)¶
Removes the specified item from the library.
Role: _library_write
Modify metadata of the items in a specific library¶
- PUT /library/(library-id)/item-metadata¶
Modify metadata of the items in a specific library
Query Parameters: - notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – JobDocument
Role: _library_write
Listing library items in batch¶
New in version 4.5.
Creating an item list job¶
- POST /library/(library-id)/list¶
Starts a new job that goes through all the items in the specific library and outputs a file to the supplied URI.
The output format depends on the specified parameter, if set to XML an ItemListDocument will be produced. Furthermore if an XSLT is given the ItemListDocument will be transformed.
Query Parameters: - destinationUri – The URI to output the CSV file to.
- outputFormat – Specifies the output format. Valid values are xml (default) and csv.
- field – A comma-separated list of metadata fields to include in the result.
- data – Specifies any additional data that should be included with the metadata fields.
- p – Comma-separated list of paths specifying the content to include. Overrides the field and data parameters. Only supported for XML output. See Content paths.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Accepts: - application/xslt – An optional XSLT capable of transforming ItemListDocument.
Produces: - application/xml, application/json – JobDocument.
Role: _library_read
Example¶
POST /library/VX*75/list?p=id,shape.containerComponent.duration&destinationUri=file:/home/user/output.xml
Content-Type: application/xml
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<jobId>VX-121</jobId>
<user>admin</user>
<started>2016-02-21T10:11:42.998+01:00</started>
<status>READY</status>
<type>LIST_ITEMS</type>
<priority>MEDIUM</priority>
</JobDocument>
$ xmllint --format /home/user/output.xml
<?xml version="1.0"?>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<item xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-47">
<shape>
<containerComponent>
<duration>
<samples>1871720000</samples>
<timeBase>
<numerator>1</numerator>
<denominator>1000000</denominator>
</timeBase>
</duration>
</containerComponent>
</shape>
</item>
<item xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-48">
<shape>
<containerComponent>
<duration>
<samples>1871763000</samples>
<timeBase>
<numerator>1</numerator>
<denominator>1000000</denominator>
</timeBase>
</duration>
</containerComponent>
</shape>
</item>
</ItemListDocument>