1. Home
  2. Programming
  3. EIDR REST API
  4. REST API – Introduction
  1. Home
  2. Programming
  3. REST API – Introduction

REST API – Introduction

Introduction

The EIDR system provides various services as summarized in the EIDR Registry Technical Overview using a REST-based interface in combination with HTTP 1.1 (see RFC 2616).

NOTE: Public services do not necessarily mean open access. Ingesting or registering data into EIDR is controlled, while reading data from EIDR is generally not restricted.

Public Services

EIDR maintains four ID registries:

  1. Content ID – Audiovisual works and related assets
  2. Video Service ID – Audiovisual content delivery services, channels, etc.
  3. Party ID – Organization ID for internal EIDR reference (used in Content and Video Service records)
  4. User ID – Client ID for internal EIDR reference (used by the EIDR access control system)

Content ID Registry API Services

EIDR provides the following public services for the Content ID Registry:

  • Resolution Service: This service allows anyone to resolve an EIDR ID to its metadata and related information. Filters may be specified to allow or disallow following alias chains. Depending on the type of resolution request, for each valid ID, the response would be one of DOI kernel metadata, simple metadata, full metadata, self-defined metadata, or provenance. For objects that are aliased, you can choose to follow or not follow the alias chain to the ultimate surviving ID, up to five levels when an alias continuation token is returned.

NOTE: Provenance resolution may be restricted based on the access privileges of a user.

  • Query Service: This service allows authenticated users to submit a query on registered metadata records and get a response. The response would be a list of records that matched the requested criteria. For complete details on how the results are screened based on the user’s access privilege, please refer to the EIDR Registry Technical Overview documents. The response is paginated.
  • Registration Service: This service allows authorized users to perform the following content operations:
  • Create Object
  • Add Relationship
  • Remove Relationship
  • Replace Relationship
  • Modify
  • Delete
  • Alias
  • Promote

For complete details about each of the operations listed, refer to the EIDR Technical Overview.

NOTE: The service allows batching identical operations on unrelated objects as part of the same request. The service returns a token for clients to check on the status of the batch. The service may also return the status as a response in order to support synchronous registrations (which have an immediate pass/fail flag). In the case of immediate pass/fail, only one operation must be part of the batch.

  • Status Lookup service: This service allows authorized users to get the status of valid content write requests that were made previously. This service accepts the following types of request:
  • Token. A token may refer to a submitted batch or a single operation (within a batch). Please refer to the EIDR schema for the various kinds of status responses.
  • User ID. The response would be a list of tokens and their status. The list includes all requests made by the user. Optionally filters may be added to this request based on either status, or range of submission timestamps, or after-timestamp to return status of requests submitted later than the one specified.
  • Registrant. The response would be a list of tokens and their status. The list includes all requests made by users of this Registrant. Optionally filters may be added to this request based on either status, or range of submission timestamps, or a timestamp to return the status of requests submitted later than the one specified.

For each of the status responses, a description may also be returned to provide more guidance to the users. Specifically:

  • When the status type is a “duplicate,” the response also includes one or more content IDs of previously registered objects. If there is only one match and that match is considered a perfect match, the ID will also be shown in the Status element.
  • When the status type is “success”, the response also includes the content ID of the newly registered object.

The response is paginated. For operation requests with immediate response flag set to true, the status is available synchronously.

  • Match Service: This follows the same general syntax of the Registration Service except that no modifications are applied to the registry. Instead, the raw results of the automated de-duplication review are returned to the user. Each record will have one of four responses:
    • Match – The record was found in the registry and the exiting EIDR ID is returned.
    • No Match – The submitted record could not be found in the registry and should be submitted for registration
    • Candidates Found – One or more possible matches has been found, but not with enough confidence for the automated process to make a definitive decision. Instead, the matching EIDR IDs are returned along with their match confidence score.
    • Error – The record could not be processed, generally due to a schema (syntax) or business rule (logic) violation.
  • Graph Traversal Service: This service allows authenticated users to request certain aspects of object relationships. The following types of sub-graphs may be requested:
    • Ancestors of an object, which may be filtered for specific referent types, structural types, and/or relationship types.
    • Descendants of an object, which may be filtered for specific referent types, structural types, and/or relationship types.
    • Series ancestry.
    • Remotest ancestor of an object.
    • Leaf descendants of an object.
    • Parent of an object.
    • Children of an object.

NOTE: If the registry encounters an object with restrictive reads during the traversal (that is, objects with a status of “in development”), the registry continues its traversal only if the user is authorized to read that object. Refer to schema for return values.

  • Modification Base Service: This service allows authenticated users to retrieve the XML required to create the object as a specified type. The returned information can be used to produce appropriate input for the Modify operation. See EIDR Registry Programmers Guide for details.
  • Permissions Service: This service allows authenticated users read the ACL (Access Control List) associated with a Content ID record.

Video Services Registry API Services

EIDR provides the following public services for the Video Services Registry:

  • Resolution Service: This service allows anyone to resolve an EIDR Video Service ID to its metadata and related information.
  • Tree Traversal Services
    • Parent: This service returns the Parent ID of a specified Video Service, if any.
    • Children: This service returns the Child ID(s) of a specified Video Service, if any.
  • Query Service: This service allows authenticated users to submit a metadata-based query on registered Video Service records and get a response that lists the records that match the requested criteria.
  • Registration Service: This service allows authorized users to create new Video Service IDs.
  • Modification Service: This service allows authorized users to modify the descriptive metadata associated with an existing Video Service ID.

PARTY Registry API Services

EIDR provides the following public services for the Party Registry:

User Registry API Services

EIDR provides the following public services for the User Registry:

  • Resolution Service: This service allows anyone to resolve an EIDR User ID to its metadata and related information.
  • Password Service: This service allows Users to change their own passwords.

DOI Proxy

See the EIDR Registry Technical Overview for a description of the DOI proxy’s behavior and parameters for EIDR ID resolutions.

API Proxy

See EIDR API Proxy for an introduction to the EIDR JSON/TSV API.

See Also

Updated on April 9, 2021

Was this article helpful?

Related Articles