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
Library settings
Library content
Listing library items in batch

Managing libraries ¶

List all libraries¶

GET /library¶

Retrieves a list of the ids of all known libraries.

Query Parameters:	first (integer) – From the resulting list of items, start return list from specified offset. Default is `1`, start return list from beginning. number (integer) – The number of entities to fetch. Default is `100`. autoRefresh (boolean) – Only list libraries with the specified auto refresh status. frequencyFrom (integer) – Only list libraries whose update frequency is greater than it. frequencyTo (integer) – Only list libraries whose update frequency is less than it. updateMode (string) – Only list libraries with the specified update mode.
Produces:	application/xml, application/json – URIListDocument containing the ids of all the libraries. text/plain – CRLF-delimited list of ids
Role:	_library_read

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.

Since the creation of the library and adding the items to the new library is done within a single database transaction, it is advisable to split the call into several put calls when adding a huge amount of items to a library.

Query Parameters:	externalId (string) – An external identifier to assign to the 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. text/plain – CRLF-delimited list of ids
Status Codes:	409 – If the external id is already in use.
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.

Query Parameters:	async (boolean) – `true` - Start a DELETE_LIBRARY job that removes the library. `false` (default) - Remove the library immediately. notification (string) – The placeholder job notification to use for this job. notificationData (string) – Any additional data to include for notifications on this job. priority (string) – The priority to assign to the job. Default is `MEDIUM` . jobmetadata (string[]) – Additional information for the job task. holdJob (boolean) – If set to `true`, the job will be created in a `HOLD` state. Default is `false`.
Produces:	application/xml, application/json – JobDocument containing library delete job.
Status Codes:	202 – The library will be removed by the returned job. 200 – The library has been deleted.
Role:	_library_write

Example¶

DELETE /library/VX*51

Delete multiple libraries¶

DELETE /library¶

Deletes the libraries with the specified ids.

Query Parameters:	id (string) – Required. Comma-separated list of library ids or external ids. async (boolean) – `true` - Start a DELETE_LIBRARY job that removes the libraries. `false` (default) - Remove the libraries immediately. notification (string) – The placeholder job notification to use for this job. notificationData (string) – Any additional data to include for notifications on this job. priority (string) – The priority to assign to the job. Default is `MEDIUM` . jobmetadata (string[]) – Additional information for the job task. holdJob (boolean) – If set to `true`, the job will be created in a `HOLD` state. Default is `false`.
Produces:	application/xml, application/json – JobDocument containing library delete job.
Status Codes:	202 – The libraries will be removed by the returned job. 200 – The libraries have been deleted.
Role:	_library_write

Example¶

DELETE /library?id=VX*50,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 xmlns="http://xml.vidispine.com/schema/vidispine">
   <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¶

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:	starttc (boolean) – `true` - Interval is given relative to start timecode of item. `false` (default) - Interval is 0-based. first (integer) – From the resulting list of items, start return list from specified offset. Default is `1`, start return list from beginning. number (integer) – The number of entities to fetch. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster. noauth-url (boolean) – `true` Return URIs that do not need authentication. `false` (default) Return normal URIs baseURI (string) – Which base URI to use for the thumbnail URLs. p (string) – Comma-separated list of paths specifying the content to include. Overrides the content and filter parameters. content (string) – Comma-separated list of the types of content to retrieve. Valid values are `metadata`, `uri`, `shape`, `poster`, `thumbnail`, `access`, `merged-access`, `external`. interval (string) – Comma-separated list time-span - Filter out metadata, return only metadata for specified time span. `generic` - Return all non-timed metadata. `all` (default) - Return all metadata, same as `interval=generic,-INF-+INF` `result` - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.) field (string) – Comma-separated list. field-name - Return specified field. field-name ”:” new-name - Return specified field, renamed to a new name in return value. “-” field-name - Exclude specified field. (default) - Return all fields. group (string) – Comma-separated list. group-name - Return specified group. group-name `+` - Return specified group and subgroups. group-name `:` new-name - Return specified group, renamed to a new name in return value. `-` group-name - Exclude specified group. (default) - Return all groups. language (string) – Comma-separated list. language-tag - Return metadata for specific language, e.g. `en_US`. Wildcards may be used, e.g. `_CA` for both Canadian French and Canadian English. `none` - Return all metadata without language specification. `all` (default) - Return all metadata, with or without language specification. sampleRate* (string) – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision. track (string) – Comma-separated list. track-type track-number - Return metadata for specified track. Example of track is `A2`. track-type t1 `-` t2 - Return metadata for specified track interval, e.g. `A2-4`. track-type `` - Return metadata for all tracks of specified type, e.g. `A`. `generic` - Return all non-tracked metadata. `all` (default) - All metadata, with or without track specification, are returned. include (string) – A list of keys. Includes additional field specific data. Additionally, if set to `type` the type definition of the field will be retrieved. includeValues (boolean) – Return the value enumeration for each metadata field. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. defaultValue (boolean) – `true` - For unset fields, return default values. `false` (default) - Do not return default values. includeTransientMetadata (boolean) – `true` (default) - Include transient metadata. `false` - Do not include transient metadata in response. revision (string) – Specifying which metadata revision to display. Only used if requesting a single item or collection. mergedType (string) – The type of operation to check for. mergedPermission (string) – The lowest required permission level. mergedExtradata (string) – Any possible extra data. uriType (string) – Comma-separated list of format types (container format) to return. scheme (string) – URI scheme to return. storageType (string) – Only return URIs for files from storages of this type. methodType (string) – Access method. `AUTO` - Gives an APInoauth URI to the media. Access to file is tunneled through VidiCore. `AZURE_SAS` - If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through VidiCore but rather point directly to the media location at the Azure storage. methodMetadata (string) – Metadata used with storage method. tag (string) – A URI parameter: Comma-separated list of shape tags to return. version (string) – Specifying which essence version to return for shapes. If special value `all`, display all versions. If special value `latest` (default), display latest version of shapes. closedFiles (boolean) – A URI parameter: `true` (default) - Return only URIs that point to closed files. `false` - Return all URIs. storage (string[]) – List of storage ids. Return only files from specific storages. Can be specified multiple times. storageGroup (string) – Storage group id. Return only files from storages specified in the storage group.
Produces:	application/xml, application/json – ItemListDocument containing the items together with the requested data.
Role:	_library_read
Role:	_metadata_read (`content=metadata`)
Role:	_item_uri (`content=uri`)
Role:	_thumbnail_read (`content=poster` and `content=thumbnail`)
Role:	_accesscontrol_read (`content=access` and `content=merged-access`)
Role:	_item_id_read (`content=external`)

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.

Since adding the items to the library is done within a single database transaction, it is advisable to split the call into several put calls when adding a huge amount of items to a 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 an item to a library¶

PUT /library/(library-id)/(item-id)¶

Adds the specified item to the library.

Role:	_library_write

Example¶

PUT /library/VX*48/VX-251

200 OK

Remove an item from a library¶

DELETE /library/(library-id)/(item-id)¶

Removes the specified item from the library.

Role:	_library_write

Example¶

DELETE /library/VX*48/VX-251

200 OK

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 (string) – The placeholder job notification to use for this job. notificationData (string) – Any additional data to include for notifications on this job. priority (string) – The priority to assign to the job. Default is `MEDIUM` . jobmetadata (string[]) – Additional information for the job task. holdJob (boolean) – If set to `true`, the job will be created in a `HOLD` state. Default is `false`.
Accepts:	application/xml, application/json – MetadataDocument the metadata to apply to the items.
Produces:	application/xml, application/json – JobDocument
Role:	_library_write

Listing library items in batch ¶

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 (string) – Required. The URI to output the CSV file to. outputFormat (string) – Specifies the output format. One of `xml` (default) and `csv`. field (string) – Comma-separated list of metadata fields to include in the result. Default is `title` data (string) – Specifies any additional data that should be included with the metadata fields. p (string) – Comma-separated list of paths specifying the content to include. Overrides the field and data parameters. Only supported for XML output. notification (string) – The placeholder job notification to use for this job. notificationData (string) – Any additional data to include for notifications on this job. priority (string) – The priority to assign to the job. Default is `MEDIUM` . jobmetadata (string[]) – Additional information for the job task. holdJob (boolean) – If set to `true`, the job will be created in a `HOLD` state. Default is `false`.
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>

Re-index autorefresh index¶

PUT /library/re-index¶

Clears and rebuilds the separate index for autorefresh library queries in OpenSearch. Requests are ignored for Solr.

Produces:	text/plain – re-indexing status.
Role:	_library_write

Re-index specific autorefresh library¶

PUT /library/(library-id)/re-index¶

Clears and re-adds the library queries indexed in OpenSearch. Requests are ignored for Solr, non-autorefreshing libraries, and libraries with update mode TRANSIENT.

Produces:	text/plain – re-indexing status.
Role:	_library_write

Libraries¶

Managing libraries¶

List all libraries¶

Example¶

Create a library¶

Example¶

Delete a library¶

Example¶

Delete multiple libraries¶

Example¶

Library settings¶

Retrieve library settings¶

Example¶

Update library settings¶

Library content¶

Retrieve library content¶

Example¶

Add multiple items to a library¶

Example¶

Add an item to a library¶

Example¶

Remove an item from a library¶

Example¶

Modify metadata of the items in a specific library¶

Listing library items in batch¶

Creating an item list job¶

Example¶

Re-index autorefresh index¶

Re-index specific autorefresh library¶

Managing libraries ¶

Library settings ¶

Library content ¶

Listing library items in batch ¶