Retrieving item information [VC 21.3 GEN]

Item content can be retrieved from different resources, the query parameters used are the same for the different resources. Below a table of the different supported resources can be seen.

Name	BASE_PATH

Name	BASE_PATH
Search	`/item`, `/search`
Specific items	`/item/{item-id}`
Libraries	`/library/{library-id}`
Collections	`/collection/{collection-id}/item`

Get item information

By using a content parameter, much information can be gathered in one single call to the API.

Get information

GET {item-content-resource}

Retrieves the types of content that are specified in content. If URIs are included then the parameters type or tag needs to be set.

Query Parameters:	includeConstraintValue (string) – Comma-separated list of fields whose “display value” should be retrieved from the metadata dataset. `all` (default) - Return the “display value” of all fields. `none` - No “display value” will be returned. The fields will only have `id` set. comma-separated field names - Return the “display value” of the specified fields. 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) – A metadata parameter, see Retrieve metadata. field (string) – A metadata parameter, see Retrieve metadata. group (string) – A metadata parameter, see Retrieve metadata. language (string) – A metadata parameter, see Retrieve metadata. sampleRate (string) – A metadata parameter, see Retrieve metadata. track (string) – A metadata parameter, see Retrieve metadata. terse (boolean) – A metadata parameter, see Retrieve metadata. include (string) – A metadata parameter, see Retrieve metadata. type (string) – A URI parameter: Comma-separated list of format types (container format) to return. tag (string) – A URI parameter: Comma-separated list of shape tags to return. scheme (string) – A URI parameter: URI scheme to return, e.g. `ftp`. closedFiles (boolean) – A URI parameter: `true` (default) - Return only URIs that point to closed files. `false` - Return all URIs. noauth-url (boolean) – If `true`, thumbnail URIs that do not need authentication are returned. If `false` (default), normal thumbnail URIs are returned. defaultValue (boolean) – A metadata parameter, see Retrieve metadata. methodType (string) – Type of storage method. When returning URIs, only use methods of this type. See Storages. methodMetadata (string[]) – Metadata used with storage method. See Storages. 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. If special value `latest-per-shapetag`, display shapes with the highest essence version number per shape tag. revision (string) – Specifying which metadata to display. Only used if requesting a single item or collection.
Produces:	application/xml, application/json – ItemDocument
Role:	_metadata_read (`content=metadata`)
Role:	_item_uri (`content=uri`)
Role:	_thumbnail_read (`content=poster` and `content=thumbnail`)
Role:	_access_control_read (`content=access` and `content=merged-access`)
Role:	_item_id_read (`content=external`)

Example

Retrieving terse metadata and thumbnails for an item.

GET /API/item/VX-123/?content=metadata,thumbnail&terse=yes

<ItemDocument id="VX-123">
    <thumbnails>
        <uri>http://example.com/API/thumbnail/VX-1/VX-123/0@1000000</uri>
        <uri>http://example.com/API/thumbnail/VX-1/VX-123/1000000@1000000</uri>
        <uri>http://example.com/API/thumbnail/VX-1/VX-123/2000000@1000000</uri>
    </thumbnails>
    <terse>
        <durationSeconds end="+INF" start="-INF">2.04</durationSeconds>
        <durationTimeCode end="+INF" start="-INF">2040000@1000000</durationTimeCode>
        <field_A end="7" start="3">ABC</field_A>
        <title end="+INF" start="-INF">This is an imported item!</title>
        <user end="+INF" start="-INF">testUser</user>
    </terse>
</ItemDocument>

Get item content in the search result

The parameters above can also be used when searching (Search). Note that only content the user has sufficient permissions for will be retrieved.

Example

Retrieving the URIs to all AVI containers that can be accessed either by HTTP or FTP for all items.

GET /API/item/?content=uri&type=avi&scheme=http,ftp

<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <item id="VX-123">
        <files>
            <uri>ftp://example.com/VX-123_VX-2189.avi</uri>
        </files>
        <timespan start="-INF" end="+INF"/>
    </item>
    <item id="VX-124">
        <files/>
        <timespan start="-INF" end="+INF"/>
    </item>
    <item id="VX-125">
        <files>
            <uri>http://example.com/VX-125_VX-3180.avi</uri>
            <uri>ftp://example.com/VX-125_VX-3180.avi</uri>
        </files>
        <timespan start="-INF" end="+INF"/>
    </item>
</ItemListDocument>

Retrieving URIs to the content of an item

The URI retrieval method is a scaled-down version of the Get information method above.

Get item URI

GET /item/(item-id)/uri

Retrieves the URI to any container contained in the item that matches the specified type or the files contained in a shape that matches the given tags.

Query Parameters:	type (string) – Comma-separated list of format types (container format) to return. tag (string) – Comma-separated list of shape tags to return. scheme (string) – URI scheme to return, e.g. `ftp`. 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 Vidispine. `AZURE_SAS` - If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage. methodMetadata (string) – Metadata used with storage method. closedFiles (boolean) – `true` (default) - Return only URIs that point to closed files. `false` - Return all URIs.
Produces:	application/xml, application/json – URIListDocument
Role:	_item_uri

Example

GET /item/VX-123/uri?type=avi&tag=lowres
Accept: application/xml

<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <uri>http://example.com/VX-123_VX-5003.avi</uri>
    <uri>ftp://user:password@example.com/VX-123_VX-5003.avi</uri>
</URIListDocument>