1. Introduction

The lookup services enables to perform identifier resolutions within the ISAN registry by issuing an HTTP GET request.

• The primary purpose of the lookup service is to resolve an ISAN for retrieving the descriptive information of the work or version identified with the ISAN.
• The lookup service can be used to to validate the ISAN check digits, to validate if an ISAN exist or to validate that an ISAN is active (and retrieve aliased active ISAN for inactivated codes)
• The lookup service can be used to resolve any Linked Identifier associated to an ISAN record in the ISAN registry. Such Linked IDs can be private identifiers, industry identifiers (AGICOA numbers, IMDB identifiers, EIDR,…), ISO identifiers (ISRC: the soundtrack recording of the AV work, ISWC: a song of the soundtrack, ISBN : the book related to the AV work…).
• The lookup service is also useful to retrieve anytime the status of a work. This is required to pool results after using the ISAN registration service or ISAN matching service: a lookup on the private identifier associated to the registration or matching application is used to pool the result of the application.

The lookup service accept various standardized formatting of the ISAN identifier, particularly it accept the ISAN URN form as defined in IETF RFC 4246. The lookup service acts therefore as a resolution service for URN representations of ISAN identifiers.

Note: only queries with a valid isanSignatureValue header  will  get the complete descriptive metadata from the lookup service. In the absence of a isanSignatureValue header, only partial discovery information is returned by the service.

2. ISAN Lookup Request

2.1. Syntax

GET /api/works/id/{filter}?idtype=string

2.2. Parameters

2.2.1 id parameter

Description: This is the identifier to lookup, it can be an ISAN or a linked ID (private ID, IMDB, EIDR, ...)

Required: Yes

Type: Path Parameter (String)

Authorized values: The identifier parameter can be :

• An ISAN, with or without the "ISAN" prefix, formatted as
  • xxxx-xxxx-xxxx-xxxx-X-xxxx-xxxx-Y or
  • xxxxxxxxxxxxxxxxXxxxxxxxxY (without separators) or
  • xxxxxxxxxxxxxxxxxxxxxxxx (without separators or check digits) or
  • xxxx-xxxx-xxxx-xxxx-X (without version part) or
  • xxxxxxxxxxxxxxxxX (without version part or separators)
  • xxxxxxxxxxxxxxxx (without version part or separators or check digits)
  • xxxx-xxxx-xxxx (root ISAN without episode part or version part or check digits):  If only the root ISAN is resolved for a single work then the work information is returned 
  • xxxxxxxxxxxx (root ISAN without episode part or version part or separators or check digits)

• An ISAN formatted as an URN (IETF RFC 4246)
  • URN: ISAN:xxxxxxxxxxxxxxxxXxxxxxxxxY

• A linked Identifier (In such case, idtype query parameter is required to specify the type of linked ID.
  • EIDR Example : 10.5240/FD9C-CC5C-27F9-A9B0-C733-M

Examples

GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N
GET /api/works/00000002E6D00000
GET /api/works/URN:ISAN:00000002E6D00000H00000000N

 

2.2.2. filter parameter

Description: The filter parameter aims to filter the set of metadata returned by the lookup in order to return only the specified field.

 

Required: No. If not present, the service will return by default the full set of metadata.

Type: Path Parameter (String)

Authorized values:

• status: the only data returned is the status of the ISAN. This filter is typically used if the only purpose of the lookup is to validate an ISAN or to get the Active ISAN for an Inactive ISAN.
• titles: the only data returned is the list of titles for the ISAN.
• participants: the only data returned is the list of participants for the ISAN. 

Examples

GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N/status
GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N/titles
GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N/participants

 

2.2.3 idtype parameter

Description: Specifies the type of identifier if the id element is not an ISAN (or URN:ISAN).

Required: Yes, but only if the id element is not an ISAN. 

Type: Path Parameter (String)

Authorized values: Refer to the idType definition to get the list of authorized idtype.

Note: to look up an idtype=private_id

• The custom X-ISAN-Authorization header is required
• The registrant of the work is the only authorized user to lookup the private identifier.

Example:

GET /api/works/10.5240/0041-B200-711D-77A7-5807-X?idtype=EIDR
GET /api/works/EP0014S?idtype=PRIVATE_ID
GET /api/works/90750-0?idtype=AGICOA

 

2.3. Request Headers

2.3.1 Authorization header

ISAN API credentials. Required for all request.

2.3.2. X-ISAN-Authorization header

ISAN Registry credentials. Required to :

• Lookup or validate the private identifier (PRIVATE_ID)

GET /api/works/12345?idtype=PRIVATE_ID
GET /api/works/12345/status?idtype=PRIVATE_ID

• Return the full dataset (ISAN lookup or any Linked ID lookup)

GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N

2.3.3. Accept header

By providing this header, users can choose the format (XML or JSON) of the server’s response. By default the server returns XML results.

• XML

header Accept: application/xml 

• JSON

header Accept : application/json

2.3.4. If-Modified-Since header

Client applications can implement conditional GET by sending If-Modified-Since headers based on the Last-Modified headers from a previous request.

• If the result has not changed since the provided date the server returns HTTP status code 304 (Not Modified). Make conditional lookup requests as much as possible to avoid altering performance and latency.
• If the user has not sent an If-Modified-Since header, the service returns the latest copy of the representation included Last-Modified header.

Example: retrieve the titles of ISAN 0000-0002-E6D0-0000-H-0000-0000-N only if  it has been modified since Fri, 02 Sep 2011 01:05:04 GMT

GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N/titles 
header Last-Modified: Fri, 02 Sep 2011 01:05:04 GMT

2.3.5. Cache-Control header

By default, expiration caching is implemented. If needed client applications can keep a representation of a resource retrieved during 7200 seconds.

To force getting the freshest representation from the server include Cache-control : no-cache. Make conditional lookup requests as much as possible to avoid altering performance and latency.

2.3.6. Pragma header

Same as above. To get the freshest representation from the server and to support legacy HTTP 1.0 caches include Pragma: no-cache. Make conditional lookup requests as much as possible to avoid altering performance and latency.

 

2.4. Response Headers

 

Headers	Description
Date	Server response date-time *
Last-Modified	Last update date-time value of the retrieved identifier *
Content-Type	Type of representation and character set :  application/xml;charset=UTF-8 or application/json;charset=UTF-8
Cache-Control	Expiration life-time  (7200 seconds)
Expires	Expiration date-time value
Content-Length	Size in bytes of the body of the representation

 

 

2.5. Response Elements

The Lookup service returns in all cases an ISANDataType element. The return type is specialized depending on the data type of the retrieved work:

Return type	Description
WorkMetadataType	When the fetched work is a non-episodic work
SerialHeaderType	When the fetched work is a serial header (serial)
EpisodeWorkMetadataType	When the fetched work is an episodic work
VersionType	When the fetched work is a version of a work
ISANDataType	When any errors occurs, the submitted identifier can’t be retrieved

 *All dates are formatted as follow: Fri, 07 Jun 2013 09:14:19 GMT

 

2.6. Errors

When an error is caused, the body response will contain an ISANDataType with an error status. For all errors, further details are available in the description field of the error status. The following table lists the possible errors that can be generated:

2.6.1. HTTP Code = 401, UNAUTHORIZED

• ERROR: THIS OPERATION REQUIRES AUTHENTICATION
  • Applies if no valid Authorization header have been submitted or
  • If  X-ISAN-Authorization header is missing or is invalid
• ERROR: USER IS BLOCKED OR CLIENT ACCOUNT IS INACTIVE
  • Applies for X-ISAN-Authorization header verification, if the user account is blocked or inactive

2.6.2. HTTP Code = 400, BAD REQUEST

• ERROR: MALFORMED ISAN NUMBER : INCORRECT CHECK DIGIT 1
  • Applies if the submitted ISAN number is not valid due to incorrect check 1 digit

• ERROR: MALFORMED ISAN NUMBER : INCORRECT CHECK DIGIT 2
  • Applies if the submitted ISAN number is not valid due to incorrect check 2 digit

• ERROR: MALFORMED ISAN NUMBER
  • Applies if the submitted ISAN number is not valid due to other reasons

• ERROR: EXTERNALIDTYPE VALUE {%1} IS INCORRECT
  • Applies if the submitted query parameter idtype does not exist

2.6.3. HTTP Code = 404, NOT FOUND

• ERROR: NO WORK FOUND - PLEASE CHECK THE PROVIDED IDENTIFIER
  • Applies if the submitted identifier has not been retrieved in the registry

2.6.4 HTTP Code = 500, INTERNAL SERVER ERROR

• ERROR: AN UNEXPECTED ERROR OCCURED - PLEASE CONTACT sysadmin@isan.org
  • Applies for any other different reasons than previously listed

 

2.7. Notes

•  A lookup on an INACTIVE ISAN returns the metadata of the corresponding ACTIVE ISAN (the inactive ISAN becomes an alias of the active ISAN). 
  • The WorkStatus element has the value INACTIVE
  • The ISAN element provides the inactive ISAN
  • The ActiveISAN element provides the ISAN of the corresponding ACTIVE work 

• A lookup on a Project ISAN (or in-development ISAN) returns the StatusType and a minimal set of data that does not permit to identify precisely the project: only the registrant of the Project ISAN has access to the full set of information provided that the custom : X-ISAN-Authorization header is set. 

 3.0. Example

#Request
curl --request GET \
 --url https://api.isan.org/api/works/ISAN%200000-0002-E6D0-0000-H-0000-0000-N \
 --header 'accept: application/json' \
 --header 'authorization: Basic bXlBcGlMb2dpbi5hcGk6bXlBcGlQYXNzd29yZA==' \
 --header 'content-type: application/json' \
 --header 'x-isan-authorization: ISANUSER bXlSZWdpc3RyeUxvZ2luOmM2ZDM4MGVlODVlYjUzMGY3NTQzOTdjNTlmNGNlYWEy' \

 

#Response
Last-Modified: Fri, 02 Sep 2011 14:09:00 GMT
Cache-Control: must-revalidate, s-maxage=7200
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 17 Feb 2020 16:55:56 GMT

{
 "@type": "WorkMetadataType",
 "status": {
   "dataType": "WORK_METADATA_TYPE",
   "workStatus": "ACTIVE",
   "isan": {
     "root": "0000-0002-E6D0", "episodeOrPart": "0000", "check1": "H", "version": "0000-0000", "check2": "N"
   }
 },
 "administrativeDetails": {
   "registrationDate": "2011-09-02 14:09:00 +0000",
   "activationDate": "2011-09-02 04:09:22 +0000",
   "lastUpdateDate": "2011-09-02 14:09:00 +0000"
 },
 "isan": {"root": "0000-0002-E6D0", "episodeOrPart": "0000", "check1": "H", "version": "0000-0000", "check2": "N"
 },
 "type": "TE",
 "kind": "A",
 "externalIdList": {
   "externalIds": [
     "java.util.ArrayList",
     [{"code": "PRIVATE_ID",
     "id": "XXXX"}]]
 },
 "titleList": {
   "titleDetails": [
   "java.util.ArrayList",
   [{"title": "Ice Age: A Mammoth Christmas",
     "language": {
     "languageLabel": "English",
     "languageCode": {
       "codingSystem": "ISO_639_2",
       "iso6392Code": "ENG }},
   "titleKind": "ORIGINAL"}]]
 },
 "yearOfReference": "2011",
 "duration": {
   "timeUnit": "MIN",
   "timeValue": 28
 },
 "colorKind": "COLOR",
 "originalLanguageList": {
   "originalLanguages": [
   "java.util.ArrayList",
   [{
     "languageLabel": "English",
     "languageCode": {"iso6392Code": "ENG"}
   }]]
 },
 "participantList": {
 "participants": [
   "java.util.ArrayList",
   [{
     "firstName": "Karen",
     "lastName": "Disher",
     "roleCode": "DIR"
   }]
]}
}