Version: 1.4, 28 May 2015 This document is provided for information purposes by the ISAN International Agency. It does not correspond to any contractual engagement by the ISAN International Agency. ISAN-IA Rue du Beulet, 1A, CH-1203 Geneva Switzerland Tel: +41 22 545 10 00 Fax: +41 22 545 10 40 Email: [email protected]ISAN REST Web Services API
75
Embed
ISAN REST Web Services API · Fax: +41 22 545 10 40 Email: [email protected] ISAN REST Web Services API . 2/75 ISAN REST Web Services API Version: 1.4 | June 3, 2015 ISAN REST Web Services
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Version: 1.4, 28 May 2015 This document is provided for information purposes by the ISAN International Agency. It does not correspond to any contractual engagement by the ISAN International Agency.
2.3 Status of a work or version of a work: StatusType 8
2.4 Non-episodic work metadata: WorkMetadataType 12
2.5 Serial header (series) metadata: SerialHeaderType 15
2.6 Episodic work metadata: EpisodeWorkMetadataType 17
2.7 Versions of works (V-ISAN): VersionType 19
3. API AUTHENTICATION __________________________________________________________________ 22
3.1. ISAN API Authorized user 22
3.2. ISAN System Authorized user 22
4. ID RESOLUTIONS: LOOKUP SERVICE _____________________________________________________ 24
4.1. Description 24
4.2. Request 25
4.2.1. Syntax 25
4.2.2. Parameters 25
4.2.3. Request Headers 27
4.3. Response 29
4.3.1. Response Headers 29
4.3.2. Response Elements 29
4.4. Errors 30
4.5. Notes 31
4.6. Examples of possible requests 31
5. ISAN REGISTRATION OR MATCHING SERVICES ____________________________________________ 43
5.1. Description 43
5.2. Request 44
5.2.1. Syntax 44
5.2.2. Parameters 44
4/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
5.2.3. Request Headers 44
5.3. Response 45
5.3.1. Response Headers 45
5.3.2. Response Elements 45
5.4. Errors 46
5.5. Examples of use 47
6. ISAN AND V-ISAN UPDATE SERVICE ______________________________________________________ 55
6.1. Description 55
6.2. Request 56
6.2.1. Syntax 56
6.2.2. Parameters 56
6.2.3. Request Headers 57
6.3. Response 57
6.3.1. Response Headers 57
6.3.2. Response Elements 57
6.4. Errors 57
6.5. Examples of use 57
7. ISAN SEARCH SERVICE _________________________________________________________________ 61
7.1. Description 61
7.2. Request 61
7.2.1. Syntax 61
7.2.2. Parameters 61
7.2.3. Response 65
7.2.3.1. Response Headers 65
7.2.3.2. Response Elements 66
7.2.4. Errors 67
7.2.5. Examples of use 68
8 APPENDIX: WORK STATUS LIFECYCLE ____________________________________________________ 73
8.1 Possible Statuses 73
8.2 Non-episodic (single) works status lifecycle 74
8.3 Serial header status lifecycle 74
8.4 Serial episode status lifecycle 75
5/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
1. INTRODUCTION
This document outlines the ISAN Rest Web Services API, a collection of http interfaces to ISAN services that enables to read and write data in the ISAN registry. Operations such as ISAN / V-ISAN resolutions (lookups) and validations, search for registered works with ISAN, registrations / editions of works and versions of works, audiovisual metadata matching, can be realized with this API. This API will evolves and be enriched with additional services whenever needed by the industry. API users can therefore contact their ISAN registration agency or ISAN international agency to submit new API needs. To be able to use this API, users should be registered as authorized users within their ISAN registration agency.
ISAN API web services produce and consume widely used standard data formats XML and JSON. The choice of using either XML or JSON format is specified in every API query by the user. Client applications should parse XML or JSON responses using a standard XML processor or a JSON parser library to address elements within the corresponding format. A web interface to test manually the ISAN Rest Web Services API is available at: http://test.isan.org/api/ (credentials required)
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
Screenshot of the ISAN API test interface ( http://test.isan.org/api/ )
Note that testing the ISAN API through the web interface does not require other technical knowledge as reading data formatted in XML or JSON. It is assumed that the reader of this document is familiar with XML, JSON and REST as well as with basic ISAN principles outlined in the ISAN user guide, the ISAN data fields description (currently under revision), and the ISAN Data Fields Appendix - List of Codes. More ISAN documents are available on http://www.isan.org/resources/.
ISANDataType is the main type definition used for most of the API requests or responses. It is defined in the xml schema: http://www.isan.org/schema/v1.11/common/common.xsd . ISANDataType is the common base definition for audiovisual content, i.e. non episodic (single) works, episodic works (serial episodes), serial headers (series) and versions of works (V-ISAN). ISANDataType provides readable only information about the status of a work, then specific descriptive metadata for series, works or versions of works is addressed by specialized type definition:
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
2.3 Status of a work or version of a work: StatusType
StatusType provides readable only information about the status of a work (see ISANDataType)
StatusType
Field Name Description
DataType Type: String ; Occurrence : 1 Describes the type of metadata that is processed, values are
- WORK_METADATA_TYPE : non episodic (single) work metadata
- EPISODE_WORK_METADATA_TYPE: episodic work metadata (serial
episode)
- SERIAL_HEADER_TYPE: serie (serial header) metadata
- VERSION_TYPE: version of a work metadata
ISANDataType
Status :: StatusType
(read only)
WorkMetadataType
EpisodeWorkMetadataType
SerialHeaderType VersionType
ISANDataType
•Status :: StatusType (read only)
9/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
#XML Example:
<common:DataType> </common:DataType>
#JSONExample
"dataType": ""
ISAN
Type: isan:isanType (See Schema: http://www.isan.org/ISAN/isan.xsd) Occurrence : 1 24 digit ISAN / V-ISAN identifier of the work or version (when applicable). Contains root, episodeOrPart,checkDigit1,version,checkDigit2
Status of the work (or version) in the ISAN registry, values are
- ACTIVE : the work or version is an active registration in the ISAN
registry.
- INACTIVE : the work / version / identifier has been inactivated in the
ISAN registry. An inactivation is always linked to an active ISAN
identifier, see ActiveISAN field for the corresponding active ISAN.
- INDEV : the work is still in development. At this stage of the production,
metadata can still change and is only available to the registrant of the
work. INDEV works are activated by the registrant once the work is
finalized, metadata becomes public and the status will then be ACTIVE.
- PENDING (registration service only): the registration processes is
pending as the work is potentially already registered with ISAN, i.e. the
submitted work is matching with one or several other works in the ISAN
registry; a duplicate check and a manual action ( web user interface) is
required to finalize the registration process.
10/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
- NO_MATCH (AV metadata matching service only): no registered work is
matching with the AV metadata in the ISAN registry.
- MATCH (AV metadata matching service only): a unique match with the
AV metadata has been found in the ISAN registry. See MatchingISANs
field for obtaining the matching ISAN identifier.
- PENDING_MATCH (AV metadata matching service only): multiple
matches with the AV metadata have been found in the ISAN registry. A
manual duplicate check is required to identify the matching work among
the several matching candidates. See MatchingISANs field for obtaining
the matching candidates ISAN identifiers.
#XML Example:
<common:WorkStatus> </common:WorkStatus>
#JSONExample
"workStatus":""
ActiveISAN Type: isan:isanType (See Schema: http://www.isan.org/ISAN/isan.xsd) Occurrence : 0 or 1 ISAN number of the active work. Applies only when the status of the described work is INACTIVE #XML Example:
MatchingISANs Type: isan:isanListType (See Schema: http://www.isan.org/ISAN/isan.xsd)
Occurrence : 0 or 1 List of ISAN numbers. Applies only for matching request when the submitted work status is MATCH or PENDING_MATCH: the list contains the matching ISAN candidate(s).
11/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
The WorkMetadataType element extends ISANDataType in the xml schema http://www.isan.org/schema/v1.11/common/common.xsd. The element WorkMetadataType defines descriptive metadata for non-episodic (single) works, it includes:
the work status description inherited from ISANDataType,
all descriptive information of the non-episodic work such as the work classification (type,
code), year of reference, duration, titles, participants, languages, production companies,
countries, ….
WorkMetadataType is returned by the lookup service when the retrieved work is a non-episodic work. WorkMetadataType is required when submitting non-episodic work registrations or non-episodic work metadata update requests. WorkMetadataType is required when submitting non-episodic work metadata matching requests. XML example of a single work description: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
2.5 Serial header (series) metadata: SerialHeaderType
The SerialHeaderType element extends ISANDataType, it is defined in the xml schema http://www.isan.org/schema/v1.21/common/serial.xsd.
The element SerialHeaderType defines descriptive metadata for serial headers (series), it includes:
the work status description inherited from ISANDataType,
all descriptive information of the serial header such as the titles, the total number of
episodes registered in the serial, the total number of seasons registered in the serial, the
duration of shortest episode, the duration of longest episode, the year of reference of
oldest episode, the year of reference of most recent episode, the most recurring
participants, the most recurring production companies.
SerialHeaderType is returned by the lookup service when the retrieved work is a serial header (serie). SerialHeaderType is required when submitting serial headers registrations or serial headers metadata update requests.
XML example of a serial header work description: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
JSON example of a serial header work description: {
"@type": "SerialHeaderType",
"status": {…},
"serialHeaderId": {
"root": ""
},
"mainTitles": {…},
"totalEpisodes": …,
"totalSeasons": …,
"minDuration": {…},
"maxDuration": {…},
"minYear": " ",
"maxYear": " ",
"mainParticipantList": {…},
"companyList": {…}
}
17/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
2.6 Episodic work metadata: EpisodeWorkMetadataType
The EpisodeWorkMetadataType element extends WorkMetadaType , it is defined in the xml schema http://www.isan.org/schema/v1.21/common/serial.xsd.
The element EpisodeWorkMetadataType defines descriptive metadata for episodic works (serial episodes), it includes:
the work status description inherited from ISANDataType,
the same descriptive information as non-episodic works such as the work classification
(type, code), year of reference, duration, titles, participants, languages, production
companies, countries, ….
specific information for episodic works: season number, episode number, the reference to
the serie / serial header ( = the root ISAN shared by the ISAN of all episodes of the serie).
EpisodeWorkMetadataType is returned by the lookup service when the retrieved work is an episodic work (serial episode). EpisodeWorkMetadataType is required when submitting episodic work (serial episode) registrations or episodic work metadata update requests. XML example of an episode work description: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
"season": " ",
"episode": " "
}
}
2.7 Versions of works (V-ISAN): VersionType
The VersionType element extends ISANDataType, it is defined in the xml schema http://www.isan.org/schema/v1.11/common/version.xsd . The element VersionType defines descriptive metadata for versions of works, it includes:
the work status description inherited from ISANDataType,
all descriptive information of the version of the work such as the kind of version and
relationship with parent work, a descriptive name, version titles, running time, languages,
color format, image dimension, image definition, image aspect ratio, media of fixation,
digital container format, countries of distribution, distribution channel, distribution platform,
VersionType is returned by the lookup service when the retrieved work is a version of work. VersionType is required when submitting version registrations or version metadata update requests. XML example of a version description:
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
4. ID RESOLUTIONS: LOOKUP SERVICE
4.1. Description The lookup services enables to perform identifier resolutions within the ISAN registry by issuing an HTTP GET request. The primary purpose of the service is to lookup an ISAN for retrieving the descriptive information of the work or version identified with the ISAN. The lookup service can also be used to lookup any “External Identifier” associated to the work or version in the ISAN registry (more than 1 Million cross references), such external 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 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. The lookup service is also useful to retrieve anytime the status of a work, this can be particularly useful when registering a work with ISAN (registration service) or matching AV metadata (matching service): in such cases users will lookup the private identifier (e.g. registration token) submitted previously with the registration or matching service. Finally the lookup service is also useful to validate ISAN identifiers, typically when transmitted in (automated) workflows. The user will therefore use the “status” filter in the request in order to validate the two check digits of the ISAN, but also check if the ISAN exist in the registry and if it is ACTIVE. Indeed, some ISAN can be inactivated (see status) and linked to an active ISAN; when an ISAN is inactive, the lookup service will provide the corresponding active ISAN (see ActiveISAN field). Users registered as ISAN registrants or ISAN readers within an ISAN registration agency will obtain the complete descriptive metadata from the lookup service. Such users will therefore lookup the ISAN
registry using their isanSignatureValue (see ISAN System Authorized user).
If no isanSignatureValue is provided in the ISAN lookup, only a reduced set of metadata is returned enabling limited lookups to users that are not registered as ISAN system users. In such cases only the folowing metadata is returned:
the work’s status description,
the WorkType code, the year of reference, the duration, up to 5 titles, up to 2 participants
In any cases all users need to be ISAN API authorized users and therefore authenticate themselves
with their apiSignatureValue (see ISAN System Authorized user)
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
4.2. Request
4.2.1. Syntax
#Request
GET /api/works/id/{filter}?idtype=string
4.2.2. Parameters
Name Description id Identifier to lookup
Required: Yes
Type: Path Parameter (String)
Valid Values : The identifier parameter can be : an ISAN number :
- 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-xxxx1 (root ISAN: without episode part or version part
or check digits) or
- xxxxxxxxxxxx (without episode part or version part or
separators or check digits)
An ISAN formatted as an URN (IETF RFC 4246)
- URN: ISAN:xxxxxxxxxxxxxxxxXxxxxxxxxY
Or an external identifier (In such case, idtype query parameter will
be required to precise the corresponding type)
See idtype definition
1 If only the root ISAN is looked up, the work information is returned in case of non episodic works (single work), but only the serial header is returned in case of epsiodic works.
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
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
filter To retrieve and extract a specific set of metadata
Required: No
Default: None If not provided, no filter is applied and the metadata description will be obtained
Type: Path Parameter (String)
Valid values:
status: to validate and retrieve the status of the identifier. titles: to return only the titles list associated to the identifier
participants: to return only the participants list associated to the identifier
More filter values are expected in future releases of the API
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
idtype Required if the type of the lookup identifier is not an ISAN or an URN:ISAN
Required: No If not provided the lookup identifier will be threaten as an ISAN number or URN
Default: None
Type: Query Parameter (String)
Valid values:
Refer to the following schema to get the list of authorized identifier’s types : http://www.isan.org/schema/v1.11/common/externalid.xsd (See idType definition)
Note: To look up from an idtype=private_id ; the custom X-ISAN-Authorization header is required Examples :
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
GET /api/works/10.5240/0041-B200-711D-77A7-5807-X?idtype=EIDR
GET /api/works/EP0014S?idtype=PRIVATE_ID2
GET /api/works/90750-0?idtype=AGICOA
4.2.3. Request Headers
Header Name Description
Authorization Required for all requests For more information refer to Authentication Header - ISAN API authorized user
X-ISAN-
Authorization Required only to : Lookup or validate a private external identifier (PRIVATE_ID)
GET /api/works/myPrivateID?idtype=PRIVATE_ID
GET /api/works/myPrivateID/status?idtype=PRIVATE_ID
Retrieve full description of any identifier
GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N
For more information refer to Authentication Header - ISAN System authorized user
Accept By providing this header, users can choose the format (XML or JSON) of the server’s response.
Accept: application/xml
Accept : application/json
By default the server returns XML results.
If-Modified-
Since
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) **, If the user has not sent an If-Modified-Since header, the service returns the latest copy of the representation included Last-Modified header.
Examples :
2 Note that only the registrant of the work is authorized to lookup a work with the private identifier registered in the ISAN Registry.
28/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
GET /api/works/0000-0002-E6D0-0000-H-0000-0000-N/titles Last-Modified: Fri, 02 Sep 2011 01:05:04 GMT
to retrieve the description of ISAN 0000-0002-E6D0-0000-H-0000-
0000-N only if it has been modified since Fri, 02 Sep 2011
Cache-Control 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 **
Pragma 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.
29/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
4.3. Response
4.3.1. 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
*All dates are formatting as follow: Fri, 07 Jun 2013 09:14:19 GMT
4.3.2. 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
30/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
4.4. Errors When an error is caused, the body response will contain an ISANDataType with an error status. For all encountered errors, API implementers should check the description field of the error status to get further details on possible causes. The following table lists the possible errors that can be generated:
HTTP CODE Description
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
401, UNAUTHORIZED ERROR: USER IS BLOCKED OR CLIENT ACCOUNT IS INACTIVE Applies for X-ISAN-Authorization header verification, if the user account is blocked or inactive
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
400, BAD REQUEST ERROR: MALFORMED ISAN NUMBER : INCORRECT CHECK DIGIT 2 Applies if the submitted ISAN number is not valid due to incorrect check 2 digit
400, BAD REQUEST ERROR: MALFORMED ISAN NUMBER Applies if the submitted ISAN number is not valid due to other reasons
400, BAD REQUEST ERROR: EXTERNALIDTYPE VALUE {%1} IS INCORRECT Applies if the submitted query parameter idtype does not exist
404, NOT FOUND ERROR : VISAN LOOKUP NOT YET IMPLEMENTED Applies if the submitted identifier is a V-ISAN. (This version of the API does not support version lookup)
404, NOT FOUND ERROR: NO WORK FOUND - PLEASE CHECK THE PROVIDED IDENTIFIER Applies if the submitted identifier has not been retrieved in the registry
500, INTERNAL SERVER ERROR
ERROR: AN UNEXPECTED ERROR OCCURED - PLEASE CONTACT [email protected] Applies for any other different reasons than previously listed
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
5. ISAN REGISTRATION OR MATCHING SERVICES
5.1. Description
These services allow users to respectively register3 or match4 a work by issuing an HTTP POST
request. For all registration or matching requests, users must authenticate by using their ISAN API user account in addition to their ISAN System user account.
This requires the HTTP Authorization header and the custom X-ISAN-Authorization header. For more information on authentication, see API AUTHENTICATION.
The registration and matching procedures are asynchronous, therefore after a successful request; the user will receive a “202-ACCEPTED” response indicating that the request will be processed. Users are invited to check for the status at a later time5, the “Location” HTTP header field of the server response indicates the address for checking the status. Note that the status of a request can also be checked with the Lookup service by performing a resolution of the private identifier (or registration token) provided as “External Identifier” in the registration or matching request. In case of an unsuccessful registration or matching request (bad requests, invalid XML …) users should check the response message body to get the causes before submitting other requests.
3 The registration of a work results in the issuance of a new ISAN for that work provided that the work was not yet registered with ISAN. 4 The matching of a work has for sole purpose to retrieve (if it exist) the ISAN of that work in the ISAN registry, by matching all work metadata with all descriptive information stored in the ISAN registry. 5 Requests are queued on an ESB and are processed sequentially according to their priorities and the load of the matching engine. The processing time depends therefore on the kind of request and the system load. In most of the cases users can expect that their request is processed in a couple of seconds and less than a minute. Note that registration requests have the priority on matching request. It is also possible that a matching requests is processed after a large bulk registration.
44/75
ISAN REST Web Services API Version: 1.4 | June 3, 2015
ISAN REST Web Services API
5.2. Request
5.2.1. Syntax
#Registration Request
POST /api/works
#Matching Request
POST /api/matchingworks
5.2.2. Parameters
Name Description
action Indicates which action to perform
Required: No If not provided the work is validated
Type: Query Parameter (String)
Valid values: validation: to validate the descriptive metadata of the work against the ISAN xml schema and for compliance with ISAN data business rules.
registration: to register the submitted work (Only for /works endpoint)
matching: to match the submitted work (Only for /matchingworks endpoint)
5.2.3. Request Headers
Header Name Description
Authorization Required For more information refer to ISAN API Authorized user
X-ISAN-
Authorization Required For more information refer to ISAN System Authorized user
Accept To specify the format of the server’s response: - application/xml
- application/json
By default the server returns XML formatted results.
Content-Type To specify the format of the request body Can be:
- application/xml
- application/json
ISAN REST Web Services API Version: 1.4 | June 3, 2015
5.3. Response
5.3.1. Response Headers
Headers Description
Date
Server response date-time
Content-Type Type of representation and character set : application/xml;charset=UTF-8 or application/json;charset=UTF-8
Location To retrieve the status of the submitted request (i.e. URL to lookup the resource)
5.3.2. Response Elements
Name Description StatusListType
(list of StatusType) If the work is valid and can be loaded, the list will contain one success status. If the work is not valid and can’t be loaded, the list will contains the errors statuses describing the reasons See XML Schema: http://www.isan.org/schema/v1.11/common/common.xsd Or StatusType Definition #XML Example:
ISAN REST Web Services API Version: 1.4 | June 3, 2015
…
]
]
}
5.4. Errors When an error is caused, the body response will contain a StatusListType containing a list of error status. For all encountered errors, the API implementer should check the description field of all element of the list to get further details on possible causes. The following table lists the possible errors that can be generated. HTTP CODE Description
401,UNAUTHORIZED ERROR: THIS OPERATION REQUIRES AUTHENTICATION Applies if no Authorization header have been submitted or If X-ISAN-Authorization header is missing
401,UNAUTHORIZED ERROR: USER IS BLOCKED OR CLIENT ACCOUNT IS INACTIVE Applies for X-ISAN-Authorization header verification, if the user account is blocked
400,BAD REQUEST ERROR: MISSING OR INVALID COLOR KIND PROVIDED
400,BAD REQUEST ERROR: MISSING OR INVALID DURATION PROVIDED
400,BAD REQUEST ERROR: MISSING OR INVALID WORK TYPE PROVIDED
400,BAD REQUEST ERROR: MISSING OR INVALID WORK KIND PROVIDED
400,BAD REQUEST ERROR: YEAR OF REFERENCE SHOULD BE GREATER THAN 1897 AND LOWER THAN %s
400,BAD REQUEST ERROR: YEAR OF FIRST PUBLICATION SHOULD BE GREATER THAN 1897 AND LOWER THAN %s
400,BAD REQUEST ERROR: PRIVATE_ID (%s) ALREADY EXISTS IN ISAN DATADABASE FOR THIS CLIENT Applies only for registration
400,BAD REQUEST ERROR: MISSING OR INVALID ORIGINAL LANGUAGE LIST
400,BAD REQUEST ERROR: RFC3066 CODE NOT YET IMPLEMENTED - PLEASE USE ISO639_2 CODE
400,BAD REQUEST ERROR: MISSING OR INVALID PARTICIPANT LIST
ISAN REST Web Services API Version: 1.4 | June 3, 2015
400,BAD REQUEST ERROR: DIRECTOR IS MISSING
400,BAD REQUEST ERROR: MISSING OR INVALID PARTICIPANT ROLE COD
400,BAD REQUEST ERROR: MISSING OR INVALID TITLE LIST
400,BAD REQUEST ERROR: AT LEAST ONE ORIGINAL TITLE IS REQUIRED
400,BAD REQUEST ERROR: MISSING OR INVALID TITLE KIND
<common:Description>ERROR: YEAR OF REFERENCE SHOULD BE GREATER THAN
1897 AND LOWER THAN 2015</common:Description>
</common:Status>
<common:Status>
<common:Description>ERROR: DIRECTOR IS MISSING</common:Description>
</common:Status>
<common:Status>
<common:Description>ERROR: AT LEAST ONE ORIGINAL TITLE IS
REQUIRED</common:Description>
</common:Status>
<common:Status>
<common:Description>ERROR: SH (0000-0003-37) HAS NOT BEEN
FOUND</common:Description>
</common:Status>
</common:statusListType>
ISAN REST Web Services API Version: 1.4 | June 3, 2015
6. ISAN AND V-ISAN UPDATE SERVICE
6.1. Description This service allows users to update metadata of a work or a version of work by issuing HTTP PUT requests.
For all update requests, users must authenticate by using their ISAN API user account in addition to their ISAN System user account.
This requires the HTTP Authorization header and the custom X-ISAN-Authorization header. For more information on authentication, see API AUTHENTICATION.
The update procedures are asynchronous, therefore after a successful request; the user will receive a “202-ACCEPTED” response indicating that the request will be processed. Users are invited to check for the status at a later time6, the “Location” HTTP header field of the server response indicates the address for checking the status. Note that the status of a request can also be checked with the Lookup service by performing a resolution of the private identifier (or registration token) provided as “External Identifier” in the registration or matching request. In case of an unsuccessful update request (bad requests, invalid data …) users should check the response message body to get the causes before submitting other requests. Note that only the registrant of a work or version is authorized to update the metadata of the work or version.
6 Requests are queued on an ESB and are processed sequentially according to their priorities and the load of the matching engine. The processing time depends therefore on the kind of request and the system load. In most of the cases users can expect that their request is processed in a couple of seconds and less than a minute. Note that registration requests have the priority on matching request. It is also possible that a matching requests is processed after a large bulk registration.
ISAN REST Web Services API Version: 1.4 | June 3, 2015
6.2. Request
6.2.1. Syntax
#Update Request
PUT /api/works/{id}
6.2.2. Parameters
Name Description
id Identifier of the work to be updated
Required: Yes
Path Parameter (String) The provided identifier parameter should be a root ISAN, an ISAN or V-ISAN number. It should represent an existing work (episodic, non episodic, series or version) The metadata to update will be provided in the content body of the request depending of the type of the work to be updated:
In case of non episodic work: a WorkMetadataType description will
be required.
In case of episodic work: an EpisodeWorkMetadataType
description will be required
Note:
Updating the root of an episodic work is not allowed; SerialHeaderId
and SerialHeaderRegistrantId information are not editable
In case of series: a SerialHeaderType description will be required
Notes:
Only titles and external identifiers are editable
And in case of version work: a VersionType description will be
required
Notes:
It’s not allowed to change the parent work of a version; ParentWork is
not editable.
In all cases, not-editable fields will be ignored if provided in the body of the request.
ISAN REST Web Services API Version: 1.4 | June 3, 2015
6.2.3. Request Headers
Same as Registration Request Headers.
6.3. Response
6.3.1. Response Headers
Same as Registration Response Headers.
6.3.2. Response Elements
Same as Registration Response Elements.
6.4. Errors
Same as Registration Errors.
6.5. Examples of use
Update work kind, year and participants of non episodic ISAN 0000-0002-E6D0-0000-H-0000-0000-N (XML input)
"descriptiveName": "Rental Blu-ray disc for Japanese market",
"subtitleLanguages":{
[
"java.util.ArrayList",
[
{
"languageCode": {
"codingSystem": "ISO_639_2",
"iso6392Code": "JPN"
}
}
]
]
},
"distributionChannel": "HOMEVIDEO",
"distributionPlatform": "RENTAL"
}
#Response
HTTP/ 1.1 202 Accepted
Date: Mon, 10 Feb 2014 16:47:05 GMT
No content
ISAN REST Web Services API Version: 1.4 | June 3, 2015
7. ISAN SEARCH SERVICE
7.1. Description
The search service allows users to retrieve a subset of data in the ISAN registry by issuing an HTTP GET request. For all search requests, users must authenticate by using their ISAN API user account in addition to their ISAN System user account.
This requires the HTTP Authorization header and the custom X-ISAN-Authorization header. For more information on authentication, see API AUTHENTICATION.
The query contains 3 kind of information:
1. Filter : search criteria via query-string parameter
2. Sorting : order criteria via query-string parameter
3. Pagination details to delimit results by page and limit via query-string parameters to manage the amount of data to retrieve per requests.
Note that the search for text (titles, participants…) is NOT case sensitive.
7.2. Request
7.2.1. Syntax
#Request
GET /api/works?filter=string&sorting=string&limit=n&page=i
7.2.2. Parameters
Name Description filter The search criteria string
Composed of a valid list of one or many search properties and values to perform a multi criteria search.
ISAN REST Web Services API Version: 1.4 | June 3, 2015
The double colon (“::”) delimiter separates the property name from the comparison value, enabling the comparison value to contain spaces. The vertical line (“|”) delimiter separates the property name/value couples. All free text in the search criteria are handled as a “CONTAINS”.
ISAN REST Web Services API Version: 1.4 | June 3, 2015
Example to retrieve all works directed by Pedro Almodovar
dir::pedro almodovar
Note : To search a participant without specifying any roles, use the “any” code
Example to retrieve all works where Clint Eatswood has participated no matter
what was his role:
any::clint eastwood
Maximum 3 participants properties are allowed
Examples:
To retrieve all feature films released on 2013 filter=“setype::SW|wktype::FF|yor::2013“ To retrieve all documentaries or films where Clint Eastwood has participated filter=”any::Clint Eastwood|wktype::DO,FF”
sorting Sort criteria: order in which items in the payload are returned
Required: No
Default: Default order is year descending (sorting=-yor)
Type: Query Parameter (String)
Valid values:
See search criteria properties excluding participant’s roles, setype and shid properties.
Notes : For each property prefixed with a dash (“-”) sort in descending order otherwise sort in ascending order.
Example to sort by year descending and title ascending sort=-yor|title
page To indicate witch page of results to retrieve. The page number is zero-based
Required: No
Default: 0 (to retrieve the first page of results).
ISAN REST Web Services API Version: 1.4 | June 3, 2015
Type: Query Parameter (Positive integer)
limit To indicate the number of results per page.
Required: No
Default: 50
Type: Query Parameter (Positive integer)
Notes : The maximum number of results per page allowed is 100
Example to retrieve the 10th page of results with 100 results per page: offset=10&limit=100
7.2.3. Response
7.2.3.1. Response Headers
Headers Description Date
Server response date-time *
Content-Range Indicate how many items are being returned and how many total items exist. Content-Range: items <FIRST>-<LAST>/<TOTAL> The total number of items is sent only for the first page of results otherwise an asterisk. Content-Range: items 1-50/3954 or items 51-100/*
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
ISAN REST Web Services API Version: 1.4 | June 3, 2015
Content-Length Size in bytes of the body of the representation
*All dates are formatting as follow: Fri, 07 Jun 2013 09:14:19 GMT
7.2.3.2. Response Elements
Name Description ISANDataListType
(array of ISANDataType) Subset of data retrieved #XML Example:
<common:isanDataListType>
<common:ISANData></common:ISANData>
<common:ISANData></common:ISANData>
…
</common:isanDataListType>
#JSONExample
{"isandatas": [
"java.util.ArrayList",
[
{ },
{ },
…
]
]
}
The following table lists the descriptive metadata returned for each ISANDataType retrieved:
Headers Description Occurrence ISAN
ISAN number of the retrieved work
1
Titles Matching titles if title property or shtitle property has been specified in the filtering parameter, original titles otherwise
1
Year of
reference Year of reference of the retrieved work or year of oldest episode in case of serial header
1
Duration Duration of the retrieved work. Not available for Serial headers.
0 or 1
ISAN REST Web Services API Version: 1.4 | June 3, 2015
Applies only if duration property has been submitted in filtering parameter or in sorting parameter
WorkType Work type’s code Not available for Serial headers. Applies only if wktype property has been submitted in filtering parameter or in sorting parameter
0 or 1
Participants Matching participants Not available for Serial headers. Applies only if at least one participant’s roles property has been submitted in filtering parameter
0 or 1
To obtain detailed information about a work, users will use the lookup service.
7.2.4. Errors
When an error is caused, the body response will contain an error status. For all encountered errors, API implementers should check this error status description to get further details on possible causes. The following table lists the possible errors that can be generated.
HTTP CODE Description
401,
UNAUTHORIZED ERROR: THIS OPERATION REQUIRES AUTHENTICATION Applies if no Authorization header have been submitted or If X-ISAN-Authorization header is missing
401,
UNAUTHORIZED ERROR: USER IS BLOCKED OR CLIENT ACCOUNT IS INACTIVE Applies for X-ISAN-Authorization header verification, if the user account is blocked
400, BAD REQUEST ERROR: THE NUMBER OF RESULTS PER PAGE CAN'T BE GREATER THAN %s
400, BAD REQUEST ERROR: SEARCH CRITERIA CAN'T BE EMPTY - AT LEAST ONE FILTER IS REQUIRED
400, BAD REQUEST ERROR: PARAMETER %s IN SEARCH CRITERIA IS INVALID
400, BAD REQUEST ERROR: PARAMETER %s IN SORT CRITERIA IS INVALID
400, BAD REQUEST ERROR: THE PAGE NUMBER SHOULD BE GREATER THAN 0 400, BAD REQUEST ERROR: SH (%s) HAS NOT BEEN FOUND
ISAN REST Web Services API Version: 1.4 | June 3, 2015
404, NOT FOUND ERROR: NO WORKS FOUND 500, INTERNAL
SERVER ERROR ERROR: AN UNEXPECTED ERROR OCCURED - PLEASE CONTACT [email protected] Applies for any other different reasons than previously listed
7.2.5. Examples of use
Retrieve all documentaries or films where Clint Eastwood has participated and order results from newest to oldest (XML Output)