External identifiers

Managing external id namespaces

Manage external identifier namespaces.

Retrieve all known namespaces

GET /external-id

Retrieves all known external id namespaces.

Produces:
Role:

_administrator

Example

GET /external-id
<ExternalIdentifierNamespaceListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <namespace>
    <name>uuid</name>
    <pattern>[A-Fa-f0-9]{8}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{12}</pattern>
  </namespace>
</ExternalIdentifierNamespaceListDocument>

Retrieve a specific namespace

GET /external-id/(namespace-id)

Retrieves the namespace with the specified name.

Produces:
Role:

_administrator

Example

GET /external-id/uuid
<ExternalIdentifierNamespaceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <name>uuid</name>
  <pattern>[A-Fa-f0-9]{8}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{12}</pattern>
</ExternalIdentifierNamespaceDocument>

Update or create a namespace

PUT /external-id/(namespace-id)

Creates or modifies a namespace with the specified name.

Accepts:
Role:

_administrator

Example

PUT /external-id/uuid
Content-Type: application/xml

<ExternalIdentifierNamespaceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <pattern>[A-Fa-f0-9]{8}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{12}</pattern>
</ExternalIdentifierNamespaceDocument>
200 OK

Delete a namespace and all external ids in that namespace

DELETE /external-id/(namespace-id)

Deletes the specified namespace together with all external ids that exist in that namespace.

Role:_administrator

Example

DELETE /external-id/uuid
200 OK

Managing external ids

Manage external ids.

The current supported resources can be seen in the table below. These are referred to as {external-id-resource} in the definitions below.

Type Path
Item /item/{item-id}/external-id
Collection /collection/{collection-id}/external-id
Library /library/{library-id}/external-id
Job /job/{job-id}/external-id
Notification .../notification/{notification-id}/external-id
Storage /storage/{storage-id}/external-id
Metadata-field /metadata-field/{field-name}/external-id
Field-group /metadata-field/field-group/{field-group-name}/external-id
Quota rule /quota/{rule-id}/external-id
Resource /resource/{type}/{resource-id}/external-id (New in 23.1.)

Retrieve all external ids for an entity

GET {external-id-resource}

Retrieves all external ids that are assigned to a particular entity.

Produces:
Role:

_external_id_read

Example

GET /storage/VX-1/external-id
<ExternalIdentifierListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>
    <entityId>VX-1</entityId>
    <entityType>Storage</entityType>
    <namespace>uuid</namespace>
    <externalId>38eebf93-2ab7-463b-ba3a-b6217bb5bca9</externalId>
  </id>
</ExternalIdentifierListDocument>
GET /storage/38eebf93-2ab7-463b-ba3a-b6217bb5bca9/external-id
<ExternalIdentifierListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>
    <entityId>VX-1</entityId>
    <entityType>Storage</entityType>
    <namespace>uuid</namespace>
    <externalId>38eebf93-2ab7-463b-ba3a-b6217bb5bca9</externalId>
  </id>
</ExternalIdentifierListDocument>

Create a new external id

PUT {external-id-resource}/(external-id)

Creates a new external id for the specified entity.

Role:_external_id_write

Note

External ids can only contain a maximum amount of 100 characters, regardless of the max size that is specified in the namespace pattern.

Example

PUT /storage/VX-1/external-id/38eebf93-2ab7-463b-ba3a-b6217bb5bca9
200 OK
PUT /storage/VX-1/external-id/38eebf93-2ab7-463b-ba3a-b6217bb5bca9
400 An invalid parameter was entered
Context: external-id
Reason: That external id is already in use by VX-1.

Clear all external ids for an entity

DELETE {external-id-resource}

Clears all external identifiers that are registered with an entity.

Role:_external_id_write

Example

DELETE /storage/VX-1/external-id
200 OK
GET /storage/38eebf93-2ab7-463b-ba3a-b6217bb5bca9/external-id
404 A resource could not be found
Type: external-id
ID: uuid_38eebf93-2ab7-463b-ba3a-b6217bb5bca9

Remove an external id

DELETE /external-id/id/(external-id)

Removes the external identifier from all entities.

Role:_external_id_write
DELETE {external-id-resource}/(external-id)

Removes the external identifier from a specific entity.

Role:_external_id_write

Example

DELETE /external-id/id/38eebf93-2ab7-463b-ba3a-b6217bb5bca9
200 OK
GET /storage/38eebf93-2ab7-463b-ba3a-b6217bb5bca9/external-id
404 A resource could not be found
Type: external-id
ID: uuid_38eebf93-2ab7-463b-ba3a-b6217bb5bca9