Collections

A collection is an ordered logical set of items, libraries and other collections.

Managing collections

Retrieve a list of all collections

GET /collection

Retrieves a list of all known collections.

Produces:
Role:

_collection_read

Create a collection

POST /collection

Generates a new collection and returns the id associated with that collection.

Query Parameters:
 
  • name – Optional name of the collection. ( optional )
Produces:
Role:

_collection_write

Delete a collection

DELETE /collection/(collection-id)

Delete specified collection.

Note that the actual items and libraries that are contained within the collection are not modified.

Status Codes:
  • 200 OK – The collection is deleted.
  • 404 Not found – Could not find the collection.
Role:

_collection_write

Rename a collection

PUT /collection/(collection-id)/rename

Renames the collection with the Identifiers collection-id.

Query Parameters:
 
  • name – Mandatory, new name of the collection.
Role:

_collection_write

Collection content

Retrieve the contents of a collection

GET /collection/(collection-id)

Return the ids of the objects contained within the collection, that has the id collection-id.

Status Codes:
  • 404 Not found – Could not find the collection.
Produces:
Role:

_collection_read

Retrieve the items of a collection

GET /collection/(collection-id)/item

Retrieves only the items of the collection. This method can be used to retrieve item content.

Changed in version 4.4: Queries on collection items will now return items in creation order by default. See indexCollectionItemOrder on how to revert back to using the insert/custom collection item ordering.

Query Parameters:
 
  • first – Integer. The index of the first element to retrieve, must be a non-zero positive integer. Default is 1.
  • number – Integer. The total number of elements to retrieve, must be on the interval [0, 100]. Default is 100.
Status Codes:
  • 404 Not found – Could not find the collection.
Produces:
Role:

_collection_read

Perform item search within a collection

New in version 4.0.

GET /collection/(collection-id)/item
PUT /collection/(collection-id)/item

Performs a search among the items in the specified collection.

Changed in version 4.4: Queries on collection items will now return items in creation order by default. See indexCollectionItemOrder on how to revert back to using the insert/custom collection item ordering.

Content Parameters:
 

See ../item-content

Query Parameters:
 
  • result
    • list (default) - Return a list of items.
    • library - Create a library with the matching items.
  • q – XML/JSON, ItemSearchDocument. Only with GET.
  • count
    • true (default) - Return hits in result.
    • false - Do not return hits in result, in order to produce results faster.
Matrix Parameters:
 
  • library – Restricts search to within library, Identifiers. Default is *, all items.
  • 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.
  • libraryId – If set, the library identified by this id will be used instead of creating a new library.
  • autoRefresh – See Self-refreshing libraries. Defaults to false.
  • updateMode – See Self-refreshing libraries. Defaults to MERGE.
  • updateFrequency – See Self-refreshing libraries. Defaults to no periodic updates.
Produces:
  • application/xml, application/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Status Codes:
Role:

_collection_read

Semantics

Note that searching can also be performed by using the HTTP method PUT using the same syntax, except for the parameter q is omitted and the ItemSearchDocument is sent in the body of the request.

Tip

There is a limit on how many items that can be returned for each call to this method. To get all items, iterate the calls, or even better in a batch scenario, use Listing items in batch.

Example

GET /collection/VX-76/item
Accept: application/xml
<ItemListDocument>
  <item id="VX-45"/>
  <item id="VX-46"/>
  <item id="VX-47"/>
  <item id="VX-62"/>
</ItemListDocument>

Add an item, library or collection to a collection

PUT /collection/(collection-id)/(id)

Adds an item, library or collection with the id id, to the collection with the id collection-id. If id is already present within the collection, this is a no-op.

Query Parameters:
 
  • type
    • collection - The object identified by id is a collection.
    • item (default) - The object identified by id is an item.
    • library - The object identified by id is a library.
  • addItems
    • true - Library items will be added individually. Only has any effect when type=library.
    • false - Library will be added to collection, not specific items.
Status Codes:
  • 200 OK – The collection, item or library was added, or already existed within the collection.
  • 400 Bad request – Cannot add a collection to itself, or the type was given an invalid value.
  • 404 Not found – Could not find the collection, item or library.
Role:

_collection_write

Remove an item, library or collection from a collection

DELETE /collection/(collection-id)/(id)

Attempts to remove specific content with the id, id, from a collection with the id collection-id.

Note that the object corresponding to the id is not altered.

Query Parameters:
 
  • type
    • collection - The object identified by id is a collection.
    • item (default) - The object identified by id is an item.
    • library - The object identified by id is a library.
Status Codes:
  • 200 OK – The item/library is removed from the collection.
  • 400 Bad request – The type was given an invalid value.
  • 404 Not found – Could not find the collection or the item/library.
Role:

_collection_write

Collection metadata

Metadata can be set on collections, in manner very similar to Metadata.

Retrieve collection metadata

GET /collection/(collection-id)/metadata

Retrieves the metadata from the specified collection.

Matrix Parameters:
 
Produces:
Role:

_metadata_read

Update collection metadata

PUT /collection/(collection-id)/metadata

Updates the metadata of the collection.

Query Parameters:
 
Accepts:
Produces:
  • application/xml, application/jsonMetadataDocument with the metadata after the changes have been applied.
Role:

_metadata_write

Searching for collections

Searching collections behaves much like Search.

Search for collections

PUT /collection

Searches for collections that matches the query.

Query Parameters:
 
  • first – Integer. The index of the first collection. Default is 1.
  • number – Integer. The number of collections to retrieve. Default is 100.
Accepts:
Produces:
Role:

_collection_read

Retrieve search history

New in version 4.0.3.

GET /collection/history

Retrieves a list of searches made by a particular user, include “Collection search ” and “Item and collection search”. The results are ordered according to timestamp, with the latest searches being first. Duplicate queries will not be retrieved.

Query Parameters:
 
  • start – Optional. If set, only searches made after this date will be retrieved.
  • maxResults – The maximum number of searches that will be retrieved. The value must be between 1 and 50, default is 10.
  • username – The name of the user that has performed the searched. If not specified, the user performing the request will be selected.
Status Codes:
  • 400 Bad request – The request was malformed.
Produces:
  • application/xml, application/jsonSearchHistoryListDocument
Role:

_item_search

Ordering collections

Collections will return their elements in the same order for every request.

Changed in version 4.4: Queries on collection items will now return items in creation order by default. See indexCollectionItemOrder on how to revert back to using the insert/custom collection item ordering.

Reordering collection elements

POST /collection/(collection-id)/order

Changes the order of the elements. Note that the reordering elements are parsed and applied in the sequence that they are supplied.

Accepts:
Produces:
  • application/xml, application/jsonCollectionDocument containing the elements in their new order.
Role:

_collection_write

Example

Starting with an unordered collection of items, we will sort it according to item id. At the start it contains items [VX-7, VX-8, VX-5, VX-6].

GET /collection/VX-1
<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-1/VX-1</loc>
  <id>VX-1</id>
  <content>
    <id>VX-7</id>
    <uri>http://localhost:8080/API/item/VX-7</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-8</id>
    <uri>http://localhost:8080/API/item/VX-8</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-5</id>
    <uri>http://localhost:8080/API/item/VX-5</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-6</id>
    <uri>http://localhost:8080/API/item/VX-6</uri>
    <type>item</type>
  </content>
</CollectionDocument>
POST /collection/VX-1/order
Content-Type: application/xml

<CollectionReorderDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <!-- Find the current first element and put VX-5 first -->
    <item id="VX-5" before="VX-7"/>

    <!-- Add the other elements after VX-5 in sequence -->
    <item id="VX-6" after="VX-5"/>
    <item id="VX-7" after="VX-6"/>
    <item id="VX-8" after="VX-7"/>
</CollectionReorderDocument>
<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1</id>
  <content>
    <id>VX-5</id>
    <uri>http://localhost:8080/API/item/VX-5</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-6</id>
    <uri>http://localhost:8080/API/item/VX-6</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-7</id>
    <uri>http://localhost:8080/API/item/VX-7</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-8</id>
    <uri>http://localhost:8080/API/item/VX-8</uri>
    <type>item</type>
  </content>
</CollectionDocument>

Folder mapped collections

It is possible to map a Vidispine collection to a folder on the file system. This means that any files of items part of the collection will be stored in a sub-folder with the same name as the collection. For a collection marked as mapped to a folder, some additional rules are enforced when it comes to collection relationships:

  • A folder mapped collection can have at most one folder mapped parent collection.
  • An item can have at most one folder mapped parent collection.

That is, the same rule that applies to files on a traditional file system.

Note

Adding an item to a folder mapped collection will not move the item files to the corresponding folder immediately as the file movement is done asynchronously in the background.

Mark a collection as folder mapped

PUT /collection/(collection-id)/map-to-folder

Marks collection collection-id as mapped to folder. Files in child items will be moved to the corresponding folder in the storages.

Role:_collection_write

Un-mark a collection as folder mapped

DELETE /collection/(collection-id)/map-to-folder

Marks collection collection-id as not mapped to folder. Files in child items will be moved to the root directory in the storages.

Role:_collection_write

Report that the folder name has changed on disk

PUT /collection/(collection-id)/folder-name

If the folder name has been changed by a user or an external program, it can be reported to Vidispine with this command. The affected file entities in the database will then be updated with the new path, and the collection name will be changed.

Query Parameters:
 
  • name – The new name of the folder (required).
Role:

_collection_write