Retrieving item information

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
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.

Matrix Parameters:
 
  • includeConstraintValue

    Optional comma separated value, specifying a list of fields whose “display value” should be retrieved from the metadata dataset. (New in 4.13.)

    • all (default) - Return the “display value” of all fileds.
    • 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.
Query Parameters:
 
  • p

    Comma separated list of paths specifying the content to include. Overrides the content and filter parameters.

    New in version 4.5.

  • content – Comma-separated list of the types of content to retrieve, possible values are metadata, uri, shape, poster, thumbnail, access, merged-access, external.
  • interval – A metadata parameter, see Get metadata.
  • field – A metadata parameter, see Get metadata.
  • group – A metadata parameter, see Get metadata.
  • language – A metadata parameter, see Get metadata.
  • sampleRate – A metadata parameter, see Get metadata.
  • track – A metadata parameter, see Get metadata.
  • terse – A metadata parameter, see Get metadata.
  • include – A metadata parameter, see Get metadata.
  • type – A URI parameter: Optional comma-separated list of format types (container format) to return.
  • tag – A URI parameter: Optional comma-separated list of shape tags to return.
  • scheme – A URI parameter: Optional URI scheme to return, e.g. ftp.
  • closedFiles

    A URI parameter:

    • true (default) - Return only URIs that point to closed files.
    • false - Return all URIs.
  • noauth-url – If true, thumbnail URIs that do not need authentication are returned. If false (default), normal thumbnail URIs are returned.
  • defaultValue – A metadata parameter, see Get metadata.
  • methodType – Optional type of storage method. When returning URIs, only use methods of this type. See Storages.
  • methodMetadata – Optional metadata used with storage method. See Storages.
  • version – Optional integer, 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. (New in 4.12.)
  • revision – Optional revision, specifying which metadata to display. Only used if requesting a single item or collection.
Produces:
Role:

_metadata_read

Role:

_thumbnail_read

Role:

_item_uri

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 – Optional comma-separated list of format types (container format) to return.
  • tag – Optional comma-separated list of shape tags to return.
  • scheme – Optional URI scheme to return, e.g. ftp.
  • storageType – Only return URIs for files from storages of this type.
  • methodType

    Optional type of 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 – Optional metadata used with storage method.
  • closedFiles
    • true (default) - Return only URIs that point to closed files.
    • false - Return all URIs.
Produces:
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>