ISAN API 3.0 - overview – ISAN

Introduction

ISAN API 3.0 is a collection of Rest web services for reading and writing information in the ISAN registry. ISAN API 3.0 enables a wide range of operations such as ISAN applications for finished works or projects or versions, search for registered ISAN, ISAN record updates, etc ...

ISAN API 3.0 is the new generation of ISAN Rest API, it replaces ISAN API 2.1 that remains available to users but is no longer maintained.

Credentials are required to use the ISAN API, such credentials are delivered to ISAN Promoters.

Users who wish to test the ISAN API 3.0 can obtain a temporary test access :

Complete the ISAN API 3.0 Test Access Form and sign it.
Return the signed ISAN API Test Access Form to cs@isan.org
You will receive your test credential

The following topics are detailed in ISAN API 3.0 documentation

ISAN API 3.0 data schema

The understanding of ISAN schema 3.0 is a prerequisite to the implementation of ISAN API 3.0. ISAN API 2.1 users should be aware that ISAN schema 3.0 differs significantly from ISAN schema 2.1. In this chapter you will also find mappings to migrate from ISAN schema 2.1 to ISAN schema 3.0.

Lean more on ISAN API 3.0 - data schema

ISAN API 3.0 swagger interface

The most straight forward resource for experimenting and learning how to use ISAN API 3.0 is the I SAN API 3.0 swagger interface. This interface gives access to all deployed services with information on required and optional fields. Examples of various kind of requests are provided enabling you to experiment, get responses, inspect data and headers and therefore learn quickly by the practice.

ISAN API 3.0 access

Learn where the ISAN API 3.0 can be found, how to use or encode your credentials and what throttling policy applies to ensure that ressources are shared evently between users.

Searching in the ISAN Registry and consulting ISAN data

/queries service enables to query the ISAN Registry for retrieving existing ISAN and corresponding data. This service is available to all API users (reader or registrant roles)

Learn more: ISAN API 3.0 - queries service

Lookup ISAN codes and linked identifiers

/records service enables to lookup existing ISAN codes for retrieving the metadata associated to that ISAN, check if an ISAN is valid and return its status and aliased ISAN in case of inactive ISAN.

/queries service enables to lookup alternate identifiers such as IMDB, EIDR, ... that are linked to an ISAN in order to translate such IDs into ISAN. Similarly, the service enables the reverse operation, i.e. translate an ISAN into alternate IDs.

Learn more: ISAN API 3.0 - lookup identifiers

New ISAN applications & ISAN data updates

/records service enables to register ISAN records. Once a new ISAN application is submitted, follow-up the progress and get the ISAN with /myisan service.

The ISAN registration service is only available to users with a registrant role.

Learn more: ISAN API 3.0 - new ISAN applications

Update ISAN data

/records service enables to update ISAN records. The ISAN update service is only available to users with a registrant role and updates are only permitted to the registrant of the ISAN.

Learn more: ISAN API 3.0 - update ISAN data

Follow-up my ISAN applications & search "My ISAN" catalogue

/myisan service enables to query "My ISAN" catalogue in the ISAN Registry. This service is only available to users with a registrant role.

"My ISAN" catalogue corresponds to all ISAN applications that have been performed by all users of my organisation regardless of the status of the application (= all users of the same client registered within an ISAN registration agency). Therefore, the service /myisan is used to

review / follow-up the status of an ISAN applications after data submission with /records (application in progress, stand by or pending for manual deduplication).
get the ISAN once it has been allocated
query all my ISAN irrespective of its status: active ISAN, project ISAN, pending ISAN (for deduplication), inactive ISAN

Learn more: ISAN API 3.0 - myisan service

/barcodes service

/barcodes service enables to create and download one or several ISAN barcode image(s) for the provided ISAN.

learn more: ISAN API 3.0 - barcodes service

ISAN Web Interface and API 3.0

The ISAN web interface and API 3.0 are both interface for the same ISAN Registry. It is convenient for developers to refer to to the web interface for a good understanding of the different processes as well as to check the result of API calls (e.g. registrations, updates, ....)

Also, when the registration application is pending because of a potential duplicate, the deduplication can only be done on the web interface so far. Therefore, in such situation it is required to connect to the web interface to deduplicate the application before retrieving the allocated ISAN with /myisan.

The sandbox web interface that corresponds to this sandbox API is http://sandbox.isan.org/130000/en/login for the TRA.

⚠️ The value 130000 in the url differs if your account is in another ISAN registration agency as the TRA.

Other services

/discovery service

The discovery service is a limited version of the /query service.

It is not recommended at this stage to use the discovery service (still contain significant bugs and lower priority in bugs fix), user better the /query service.

learn more: ISAN API 3.0 - discovery service

/admin service

Admin service is reserved to ISAN-IA for the management of the ISAN Registry.