EIDR API Proxy – 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). In addition, EIDR uses an Enhanced API Proxy to provide additional services without impacting the primary API interface (and therefore without impacting existing API integrations).

NOTE: Public services do not necessarily mean open access. ID resolution is not generally restricted, while more advanced features, such as query, are.

API Proxy Services

The API Proxy allows certain functions not supported directly by the XML-native EIDR API, including:

  • New resolution formats: JSON, TSV
    • Empty column filtering (in TSV format)
  • Bulk resolution (multiple  identifiers at once)
  • Improved queries
    • Basic record sorting
    • Pass-through EIDR XPath queries
    • JSON queries

NOTE: The API Proxy only supports read transactions. All write and match transactions must pass through the standard EIDR API.

Return Type and Format

The API Proxy supports these EIDR resolution types for all EIDR registries, passed as a type=TYPE parameter:

  • Full – The full EIDR metadata record
  • DOIKernel – The full EIDR record cast as a DOI Kernel record

It supports these additional resolution types for the Content ID registry only:

  • SelfDefined – Metadata unique to the record (excludes inherited values)
  • Simple – A record summary, suitable for compact lists
  • Provenance – Basic administrative data regarding the record, limited by the user’s credentials
  • AlternateIDs – A list of all of the Alternate Identifies associated with an EIDR record.
  • LinkedAlternateIDs – A list of all of the Alternate Identifies associated with an EIDR record and the URLs to resolve those third-party identifiers that are publicly resolvable.

NOTE: If no type is specified, then Full is returned.

The data may be returned in two different data formats, which may be specified in the Header as a MIME type or passed as a format=FORMAT parameter:

  • json
  • tsv (tab-separated values: a.k.a., flat file)

NOTE: If no format is specified, then JSON is returned.

It is also possible to convert EIDR-compliant JSON directly into the EIDR TSV (tab-separated value) format using the JSONtoTSV function.

If you require XML-formatted data, then you should use:

  • The DOI Proxy for XML-based ID resolution (although the API Proxy will redirect simple XML resolution requests to the DOI Proxy)
  • The EIDR Mirror Registry for XML-based ID resolution and queries
  • The EIDR Primary Registry for XML-based match and write operations (create and modify)
  • The EIDR Web UI’s “View XML” option to review XML-based submission and return values

NOTE: Both type and format are case-insensitive, but by convention are presented in all lowercase.

ID Resolution

This service allows anyone to resolve an EIDR ID to its metadata and related information.  It supports these EIDR registries:

  • Content ID – DOI Prefix 10.5240
  • Video Services ID – DOI Prefix 10.5239
  • Party ID – DOI Prefix 10.5237

NOTE: Any XML format ID resolution requests submitted to the API Proxy are automatically forwarded to the DOI Proxy.

Query Service

This service allows authenticated users to submit a query on registered metadata records and get a response. The response is a list of records that match the requested criteria. Queries may be submitted in one of two formats:

  • Standard EIDR XPath query
  • JSON query

Query supports two additional parameters, sort=SORT-FIELD and order=DIRECTION.

The sort parameter can be one of the following sort keys:

  • title – ResourceName
  • date – ReleaseDate
  • length – ApproximateLength
  • coo – CountryOfOrigin
  • struct – StructuralType
  • reftype – ReferentType
  • lang – OriginalLanguage

The sort parameter can be one of the following:

  • asc – Sort in ascending order
  • desc – Sort in descending order

Sorting is done as sensibly as possible:

  • title, struct, and reftype are sorted alphabetically
  • date is sorted in date order.
  • length is converted to seconds and sorted numerically.
  • coo and lang are both arrays. The relevant parts of the items in the array (the countries for coo and the language without mode or type for lang) are extracted, sorted alphabetically, and concatenated to produce a value for comparison. For example, CountryOfOrigin:[“IE”, “GB”] is compared as “GB, IE” and an OriginalLanguage element containing  hi (Hindi) and en (English) is compared as “en, hi”, ignoring the mode and type attributes.

API Proxy queries also support the standard EIDR pageNumber and pageSize parameters. See EIDR 2.6 REST API Reference. If these are specified, then the query results will be sorted within each page, but the individual page contents will be as supplied by the registry.

See Also:

Updated on April 5, 2021

Was this article helpful?

Related Articles