OpenSpecimen exposes REST APIs that can be consumed to developed custom interfaces and for integration with other databases. The REST APIs will be consumed by the OpenSpecimen user interface.

Common Characteristics of REST Resources

...

On this page, when a portion of a URL, path, or parameter value is shown in italics, it indicates that you should replace the italicised value with a particular value appropriate to your request.

Authentication

Majority of OpenSpecimen REST APIs can be invoked only by authenticated users. There are two ways to authenticate:

1. Basic authorisation using by setting HTTP Authorization header in every API invocation request header. This can be used only for authentication of "openspecimen" domain (default domain) users. The "Authorization" header value needs to be encoded in base64 i.e. base64.encode(username + ":" + password) where base64 represents codec object
2. Using sessions API to authenticate and passing the token returned by the API in every API subsequent APIs invocation request header.

...

1. Invoke sessions API with appropriate values for username, password, and domain
   
   

   HTTP Method	POST
   URL	http[s]://<host>:<port>/openspecimen/rest/ng/sessions
   Body	Code Block { "loginName": "admin@admin.com", "password": "Login!@3", "domainName": "openspecimen" }
   Response	HTTP 200 OK response with following body Code Block { "id": 1, "firstName": "Admin", "lastName": "Admin", "loginName": "admin@admin.com", "token": "NTQ1ZjZkYjktNTUyNi00YzM4LTlkNmEtYjllM2VjNDA0ZmIz", "admin": true, "instituteAdmin": false }

   
   

2. Use the token field value returned by sessions API as X-OS-API-TOKEN HTTP header value in every API request made to OpenSpecimen. The token value is used by OpenSpecimen to establish - a) the user is authenticated, and b) to retrieve user details from database for authorisation and other purposes in request handling.

Unauthenticated APIs

Given below is list of APIs that do not require user authentication

...