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

Common Characteristics of REST Resources

...

• You access a resource by sending an HTTP request to the OpenSpecimen server. The server replies with a response that either contains the requested data you requested or a status indicator, and in some cases both.

• All resources are located at http[s]://<host-name>:<port>/<application name>/rest/ng. 

  E.g. http://demo.openspecimen.org/openspecimen/rest/ng/collection-protocols/1/workflows

  
  

• You request a particular resource by appending a particular path to this base URL
• All resources may return any of the below mentioned status codes:

...

Majority of OpenSpecimen REST APIs can be invoked only by only the authenticated users. Authentication is done by invoking the sessions API with valid credentials and using the token returned by the API  in subsequent API invocation request headers. The workflow is explained below:

1. Invoke sessions API with valid credentials i.e. username, password, and domain. When domain is not specified, it defaults to 'openspecimen'.
   
   

   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

...