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 email@example.com
- You will receive your test credential
⚠️ ISAN API 3.0 is operational since 2022 and might still have some 'youthful bugs', if you are confronted to a problem, please send us your feedback (with curl examples in case of issues) to firstname.lastname@example.org.
Note that this documentation is currently under writing, it is still incomplete and evolving regularly. If you have a specific question for which you can't find an answer, please with us at email@example.com
The following topics are detailed in ISAN API 3.0 documentation
ISAN API 3.0 fully supports ISAN schema 3.0. The understanding of ISAN schema 3.0 is a prerequisite to the implementation of ISAN API 3.0.
Note to API 2.1 users: ISAN schema 3.0 differs significantly from ISAN schema 2.1
lean more: ISAN API 3.0 - data schema and find information to migrate from ISAN schema 2.1 to ISAN schema 3.0
The most straight forward resource for experimenting and learning to use API 3.0 is the ISAN API 3.0 swagger interface. This interface give access to all deployed services with information on required and optional fields. Examples of various kind of requests are provided to perform test. It is also a Rest client, enabling users to invoke services and get responses, inspect data and headers.
Learn how to access the ISAN API 3.0, how to use or encode your credentials and what throttling policy applies to ensure that ressources are shared evently between users.
Read more on ISAN API 3.0 access
/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
/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
The ISAN registration service is only available to users with a registrant role.
Learn more: ISAN API 3.0 - new ISAN applications
/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
/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 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.
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 is reserved to ISAN-IA for the management of the ISAN Registry.