...

...

...

...

...

...

...

...

...

...

...

-

...

-

...

The purpose of this document is to explain the caTissue Plus REST APIs. 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 caTissue User Interface (built in backbone.js) as well as available for usage for integration with other systems, building plugins or building custom User Interfaces.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, 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
• All resources may return any of the below mentioned status codes:

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

Authentication

caTissue REST API's are signed requests, accessible to all the users who has access to caTissue application. To access the REST API's user need to pass their caTissue credentials by setting them in request Authorization header. The username/password should be encoded in base 64 encoding scheme.

Modules

Specimen Resources

catissuecore/rest/specimens

Creates the specimen object.

Request

Response 

catissuecore/rest/specimens

Updates the specimen object.

Request

Response 

catissuecore/rest/specimens

Retrieves the specimen with given label/bracode

Request

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 

catissuecore/rest/specimens/{label}/aliquots

This will create aliquots for the specified specimen label.

Request

Response 

catissuecore/rest/specimens/{label}/derivatives

This will create derivative for the specified specimen label.

Request

Response 

Specimen Collection Group Resource

catissuecore/rest/specimenCollectionGroups

Creates the specimen collection group.

Request

Response 

catissuecore/rest/specimenCollectionGroups

updates the specimen collection group.

Request

Response 

catissuecore/rest/specimenCollectionGroups

Retrieves the specimen collection group with the name.

Request

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

Response 

...

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:

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

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