ISAN API 3.0 url
To access the API from a Rest client use the base url: http://sandbox.isan.org/api/v3/
To access the API from an internet browser, use the ISAN API 3.0 swagger interface
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:
- authentication to the API (Authorisation header) required to unlock the access to the API
- 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 :
|ISAN role||User profile||authorized functions||authorized service|
|reader||anyone who need to search for existing ISAN||search for ISAN , view ISAN data||
ISAN search & view
My ISAN updates
ISAN Version registration
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:
|X-RateLimit-Limit-rate_isanQueries_[your IP address]||Applicable rate limit for the service (e.g. 10)|
|X-RateLimit-Remaining-rate_isanQueries_[your IP address]||Remaining requests in the time period (e.g. 9)|
|X-RateLimit-Reset-rate_isanQueries_[your IP address]||
remaining time in ms until reset (e.g 60000)