ISAN API 3.0 - access

ISAN API 3.0 Sandbox versus Production

Developper and API evaluators are using the ISAN API 3.0 sandbox. The sandbox is connected to an altered ISAN database that contains fake information modified ISAN records, etc.. that is the result of the various tests and trials performed by API users. 

Important: One should never trust information that is pulled from the sandbox API, and never use sandbox ISAN in real applications.

Sandbox ISAN shall never be considered as real ISAN!

The production API is only to be used by validated ISAN API applications.

ISAN API 3.0 url

Sandbox

• from a Rest client use the base url: http://sandbox.isan.org/api/v3/ (sandbox)
• ISAN API 3.0 swagger interface (sandbox)

Production

• from a Rest client use the base url: https://api.isan.org/api/v3/ (production)
• ISAN API 3.0 swagger interface (production)

ISAN API 3.0 access control

Access to the ISAN API is restricted to authorised users. 

credentials are delivered by ISAN-IA or an ISAN registration agency (learn how to obtain test credentials).

The ISAN API requires two levels of authentication:

1. authentication to the API (Authorisation header) required to unlock the access to the API
2. authentication in the ISAN Registry (X-ISAN-Autorization header) to authorize the functions defined by your user role (e.g. "reader" to search, "registrant" to register new ISAN)

Read the following article ISAN API Authentication to understand how to use and encode ISAN API credentials.

ISAN registry roles

Authorized users have only access to services that are in the scope of their user role. The user role is defined by the registration agency based on the needs and the profile of the ISAN API user. There are two main roles :

How to authenticate in the ISAN swagger interface

Open ISAN API 3.0 swagger interface with your favorite browser and select the POST /queries service

📒To login, you can also click on the lock icon displayed at the to right header of each service. 

ISAN API 3.0 throttling

To allocate seamless resources to all API users and prevent the API from being overwhelmed by too many requests by some users, the API Gateway throttles requests. The current (experimental) limits are the following:

• /discovery service: 2 request per minute
• /barcodes, /records, /queries : 5 request per second

If the limits is reached, the API returns an http error 429: too many requests to the Rest client. Upon catching such exceptions, the client can resubmit the failed requests in a way that is rate limiting, while complying with the API Gateway throttling limits.

Every response header contains 3 useful information to prevent such situations: