External identifiers¶

Managing external id namespaces
Managing external ids

Managing external id namespaces ¶

Manage external identifier namespaces.

Retrieve all known namespaces ¶

GET /external-id¶

Retrieves all known external id namespaces.

Produces:	application/xml, application/json – ExternalIdentifierNamespaceListDocument
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:	application/xml, application/json – ExternalIdentifierNamespaceDocument
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:	application/xml, application/json – ExternalIdentifierNamespaceDocument
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:	application/xml, application/json – ExternalIdentifierListDocument
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