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
The following characteristics apply to all OpenSpecimen API resources:
- You access a resource by sending an HTTP request to the OpenSpecimen server. The server replies with a response that either contains the 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.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:
| code | Applies to | Status Message |
|---|---|---|
| 200 | All resources | |
| 201 | All POST/PUT requests | Resource created/updated successfully |
| 400 | All requests | Invalid parameters, this will also include application specific error messages |
| 401 | All requests | Authorization failed |
| 403 | All requests | |
| 404 | All requests | Resource not found, also includes specified resource id/name/title |
| 500 | All requests | Internal server error |
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
OpenSpecimen REST APIs can be invoked only by authenticated users. There are two ways to authenticate:
- Basic authorisation using HTTP Authorization header. This can be used only for authentication of "openspecimen" domain (default domain) users. The "Authorization" header value needs to be encoded in base64.
- Using sessions API to authenticate and passing the token returned by the API in every API invocation request header.
Unauthenticated APIs
Given below is list of APIs that do not require user authentication
| HTTP Method | URI | Description | Why? |
|---|---|---|---|
| GET | /institutes | Retrieve list of institutes provisioned in database | To populate institute dropdown in user sign-up UI form |
| GET | /institutes/byname | Retrieve details of institute by name. Details include, for example, list of departments | To populate departments dropdown in user sign-up UI form |
| GET | /config-settings/locale | Retrieve locale settings like locale (en-US, en-UK), date/time format in use | To initialise UI app resource bundle |
| GET | /config-settings/app-props | Retrieve details like list of installed plugins, build version, build date etc | To load and initialise plugin resources, and display build information |
| GET | /auth-domains | Retrieve list of authentication domains provisioned in database | To populate domain dropdown in user sign-in UI form. The dropdown is displayed iff more than one authentication domains are configured |
| POST | /sessions | Authenticate user credentials and obtain token for use in subsequent rendezvous with OpenSpecimen | Used in implementation of sign-in UI form. |
| POST | /users/reset-password | Reset user password based on login name and valid reset token issued by OpenSpecimen | Used in implementation of forget password and reset password UI workflow |
| POST | /users/forgot-password | Validates user login name and sends reset password link to user email ID | Used in implementation of forget password UI workflow |
| POST | /users/sign-up | Create a new user in pending status. The user has to be approved by admin to allow further use of OpenSpecimen | Used in implementation of sign-up UI workflow |
Date & Time Handling
OpenSpecimen assumes all date/time values specified in API request payload to be in UTC. The UTC time is then converted to server timezone before storing in database. This is best explained using an example:
- Assume OpenSpecimen is running in Mountain time (MT).
- Assume the API caller specified the date field value as "2017-02-20" in API request payload.
- The server interprets the input value ("2017-02-20") to be in UTC timezone and converts it to "2017-02-19" MST. This is because MT is 6 or 7 hrs behind UTC.
- The MT value ("2017-02-19") is then persisted into database.
This is surprising and undesirable behaviour from API users point of view.
In order to solve this problem, the API caller should always provide date/time field values in UTC using either of following options:
Milliseconds elapsed since epoch. This mode always represents time in UTC. For example: 1487574000000 is 20th February 2017 00:00 in MDT
{ "lastName": "Blackberry", "birthDate": 1487574000000, "pmis": [] }Adding appropriate offset to input date/time field value. For example: 2017-02-20T06:00:00.000Z is 20th February 2017 00:00 in MDT
{ "lastName": "Blackberry", "birthDate": "2017-02-20T07:00:00.000Z", "pmis":[] }