...

-

...

The purpose of this document is to explain the caTissue REST API to be used for communicating with other applications. caTissue expose REST API for performing add/update/search operation on Specimen, SpecimenCollectionGroup and creating aliquots/derivatives for the parent specimen-

Table of Contents

OpenSpecimen exposes REST APIs that can be consumed to develop custom UI 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 caTissue OpenSpecimen API resources:

You access a resource by sending an HTTP request to the caTissue OpenSpecimen server. The server replies with a response that either contains the requested data you requested, or a status indicator, or and in some cases both.
All resources are located at http[s]://<host-name>:<port>/
catissuecore
<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 that specifies the resource.
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.

List of resources which are accessible through REST

Specimen Resource

catissuecore/rest/specimens

Creates the specimen object.

Request

Method URL

POST catissuecore/rest/specimens

accept

application/json

{"label":"testLabel","className":"Tissue","type":"Not Specified","barcode":"12345","createdDate":"Jul 31, 2013 11:16:14 AM","availableQuantity":2.0,"activityStatus":"Active","isToPrintLabel":false}

Response

Status

Response

201

application/json

{"id":1,"label":"testLabel","className":"Tissue","type":"Not Specified","barcode":"12345","createdDate":"Jul 31, 2013 11:16:14 AM","availableQuantity":2.0,"activityStatus":"Active","isToPrintLabel":false}

403

{"error":"User is not authorized to create the specimens"}

500

{"error" : "Something went wrong. please try again later"}

catissuecore/rest/specimens

Updates the specimen object.

Request

Method URL

PUT catissuecore/rest/specimens

accept

application/json

{"id":1,"label":"testLabel","className":"Tissue","type":"Not Specified","barcode":"12345","createdDate":"Jul 31, 2013 11:16:14 AM","availableQuantity":2.0,"activityStatus":"Closed","isToPrintLabel":false}

Response

Status

Response

201

application/json

{"id":1,"label":"testLabel","className":"Tissue","type":"Not Specified","barcode":"12345","createdDate":"Jul 31, 2013 11:16:14 AM","availableQuantity":2.0,"activityStatus":"Closed","isToPrintLabel":false}

403

{"error":"User is not authorized to create the specimens"}

500

{"error" : "Something went wrong. please try again later"}

catissuecore/rest/specimens

Retrieves the specimen with given label/bracode

Request

Method URL

GET catissuecore/rest/specimens

Parameters

label=label to be searched or

barcode=barcode to be searched

catissuecore/rest/specimens/label=tissue_specimen, this will return the specimen with label "tissue_specimen"

catissuecore/rest/specimens/barcode=23457, this will return the specimen with barcode "23457"

Response

Status

Response

200

application/json

{"id":1,"label":"testLabel","className":"Tissue","type":"Not Specified","barcode":"12345","createdDate":"Jul 31, 2013 11:16:14 AM","availableQuantity":2.0,"activityStatus":"Active","isToPrintLabel":false}

404

{"error" : "No Specimen found with given label/barcode <label/barcode>"}

500

{"error" : "Something went wrong. please try again later"}

catissuecore/rest/specimens/{label}/aliquots

This will create aliquots for the specified specimen label.

Request

Method	URL
POST	catissuecore/rest/specimens/{label}/aliquots
accept	application/json

Response

Status	Response
200	application/json
403	{"error":"User doesn't have specimen processing privileges"}
404	{"error":"Parent with label/barcode <label/barcode> doesn't exist
500	{"error" : "Something went wrong. please try again later"}

catissuecore/rest/specimens/{label}/derivatives

This will create derivative for the specified specimen label.

Request

Method	URL
POST	catissuecore/rest/specimens/{label}/derivatives
accept	application/json

Response

Status	Response
200	application/json
403	{"error":"User doesn't have specimen processing privileges"}
404	{"error" : "Parent with given label/barcode <label/barcode> doesn't exist"}
500	{"error" : "Something went wrong. please try again later"}

Specimen Collection Group Resource

catissuecore/rest/groups

Creates the specimen collection group.

Request

Method	URL
POST	catissuecore/rest/groups
accept	application/json

Response

Status	Response
200	application/json
403	{"error":"User doesn't have privileges to create Specimen collection group"}
500	{"error" : "Something went wrong. please try again later"}

catissuecore/rest/groups

updates the specimen collection group.

Request

Method	URL
PUT	catissuecore/rest/groups
accept	application/json

Response

Status	Response
200	application/json
403	{"error":"User doesn't have privileges on this Specimen collection group"}
500	{"error" : "Something went wrong. please try again later"}

catissuecore/rest/groups

Retrieves the specimen collection group with the name.

Request

Method	URL
GET	catissuecore/rest/groups
parameters	title: the specimen collection group will searched on the basis of title.

catissuecore/rest/groups/title=scg1, this will search for the collection group having title as "scg1"

Response

...

Authentication

Majority of OpenSpecimen REST APIs can be invoked only by 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:

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 }

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

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
Code Block
language js
{ "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
Code Block
language js
{ "lastName": "Blackberry", "birthDate": "2017-02-20T07:00:00.000Z", "pmis":[] }
Adding appropriate offset to input date/time field value. For example: 2017-02-20T00:00:00.000-0700 is 20th February 2017 00:00 in MDT
Code Block
language js
{ "lastName": "Blackberry", "birthDate": "2017-02-20T00:00:00.000-0700", "pmis":[] }

Modules

Child pages (Children Display)

Versions Compared

Old Version 4

New Version Current

Key

Common Characteristics of REST Resources

List of resources which are accessible through REST

Specimen Resource

Specimen Collection Group Resource

Authentication

Date & Time Handling

Modules

Page Comparison

Versions Compared

Old Version 4

New Version Current

Key

Common Characteristics of REST Resources

List of resources which are accessible through REST

Specimen Resource

Specimen Collection Group Resource

Authentication

Date & Time Handling

Modules