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: Do Not Use Sandbox data in Production: Information from the Sandbox API is strictly for testing. Never trust, store, or distribute ISANs obtained from the Sandbox, as they are simulated records and will not resolve in the official ISAN Registry.
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:
- 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 |
/queries /barcodes |
| registrant |
|
ISAN search & view ISAN registration My ISAN updates ISAN Version registration |
/queries /barcodes /records /myisan |
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) |