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, 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 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 still in beta test, users might therefore experience known and unknown bugs. Please send us your feedback (with curl examples in case of issues) to firstname.lastname@example.org.
Please note that this documentation is currently been written, it is still incomplete and evolving regularly.
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
The ISAN registration service is only available to users with a registrant role.
The ISAN update service is only allowed in "My ISAN" catalogue (ISAN registered by users within my organisation).
Learn more: ISAN API 3.0 - records service
/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.