Key-value metadata

Some resources support basic key-value metadata (not to be confused with item metadata). This metadata is not indexed nor is it revision controlled. The role required to use the metadata depends on the resource.

Changed in version 4.12: Keys can now be hierarchical, meaning the key can include the slash character.

Supported resources

The resources that support key-value metadata can be seen in the table below. These are referred to as {key-value-metadata-resource} the the definitions below.

Resource URI Read role Write role
Groups /group/{group-name}/metadata _group_read _group_write
Users /user/{username}/metadata _admininstrator _administrator
Storages /storage/{storage-id}/metadata _storage_read _storage_write
Storage methods /storage/{storage-id}/method/{method-id}/metadata _storage_read _storage_write
Storage groups /storage/storage-group/{storagegroup-name}/metadata _storage_group_read _storage_group_write
Metadata fields /metadata-field/{field-name}/metadata _metadata_field_read _metadata_field_write
Metadata field groups /metadata-field/field-group/{group-name}/metadata _metadata_field_group_read _metadata_field_group_write
Shapes /item/{item-id}/shape/{shape-id}/metadata _shape_read _shape_write
Shape components /item/{item-id}/shape/{shape-id}/component/{component-id}/metadata _shape_read _shape_write
Files /storage/{storage-id}/file/{file-id}/metadata _file_read _file_write
Task groups /task-group/{groupname}/metadata _admininstrator _admininstrator

Managing key-value metadata

Retrieving all metadata

GET {key-value-metadata-resource}

Retrieves all key-value pairs associated with the specified entity.

Produces:

Example

GET /user/myuser/metadata
<SimpleMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <key>occupation</key>
    <value>developer</value>
  </field>
  <field>
    <key>location</key>
    <value>London</value>
  </field>
</SimpleMetadataDocument>

Retrieving all metadata for a subtree

New in version 4.12.

GET {key-value-metadata-resource}/(keypath)

Retrieves all key-value pairs associated with the specified key path. The key path can contain \* for a wildcard segment, or \*\* for any number of arbitrary segments.

Produces:

Example

GET /user/myuser/metadata/**/id

Setting multiple key-value pairs

PUT {key-value-metadata-resource}

Sets all the specified key-value pairs.

Accepts:
PUT {key-value-metadata-resource}/(prefix)

Sets all the specified key-value pairs, prefixed by key path. Key path may not contain wildcards.

New in version 4.12.

Accepts:

Example

PUT /user/myuser/metadata
Content-Type: application/xml

<SimpleMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <key>occupation</key>
    <value>developer</value>
  </field>
  <field>
    <key>location</key>
    <value>London</value>
  </field>
</SimpleMetadataDocument>
200 OK

Clearing all key-value pairs

DELETE {key-value-metadata-resource}

Clears all key-value pairs for the specified entity.

Example

DELETE /user/myuser/metadata
200 OK

Retrieving the metadata for a specific key

GET {key-value-metadata-resource}/(keypath)

Retrieves the value of a specific key. If a key path is specified, exactly one key-value pair must match the key path, else an error is returned.

Changed in version 4.12: Key paths can now be specified as well as specific keys.

Produces:
  • text/plain – The raw string value.

Example

GET /user/myuser/metadata/location
London

Setting the value for a specific key

PUT {key-value-metadata-resource}/(keypath)

Sets the value for a specific key. The key path may not contain wildcards.

Accepts:
  • text/plain – The raw string value.

Example

PUT /user/myuser/metadata/location
Content-Type: text/plain

Stockholm
200 OK

Delete key-value pairs

DELETE {key-value-metadata-resource}/(keypath)

Deletes the key-value pair with the specified key. If a key path is given, it may include wildcards for deleting multiple keys.

Changed in version 4.12: Key paths can now be specified as well as specific keys.

Example

DELETE /user/myuser/metadata/location
200 OK