External identifiers reference [VC 21.3.1 GEN]

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`

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

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