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.
Common Characteristics of REST Resources
The following characteristics apply to all caTissue API resources:
- You access a resource by sending an HTTP request to the caTissue server. The server replies with a response that either contains the data you requested, or a status indicator, or both.
- All resources are located at
http[s]://<host-name>:<port>/catissuecore/rest. - You request a particular resource by appending a particular path to this base URL th
- at 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 includes 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, this indicates that you should replace the italicized 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.
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} |
| 400 | {"error": <any application specific error>} |
| 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} |
| 400 | {"error": <any application specific error>} |
| 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} |
| 400 | {"error": <any application specific error>} |
| 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 |
| 400 | {"error": <any application specific error>} |
| 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 |
| 400 | {"error": <any application specific error>} |
| 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/specimenCollectionGroups
Creates the specimen collection group.
Request
| Method | URL |
|---|---|
| POST | catissuecore/rest/specimenCollectionGroups |
| accept | application/json |
Response
| Status | Response |
|---|---|
| 200 | application/json |
| 400 | {"error": <any application specific error>} |
| 403 | {"error":"User doesn't have privileges to create Specimen collection group"} |
| 500 | {"error" : "Something went wrong. please try again later"} |
catissuecore/rest/specimenCollectionGroups
updates the specimen collection group.
Request
| Method | URL |
|---|---|
| PUT | catissuecore/rest/specimenCollectionGroups |
| accept | application/json |
Response
| Status | Response |
|---|---|
| 200 | application/json |
| 400 | {"error": <any application specific error>} |
| 403 | {"error":"User doesn't have privileges on this Specimen collection group"} |
| 500 | {"error" : "Something went wrong. please try again later"} |
catissuecore/rest/specimenCollectionGroups
Retrieves the specimen collection group with the name.
Request
| Method | URL |
|---|---|
| GET | catissuecore/rest/specimenCollectionGroups |
| parameters | title: the specimen collection group will be searched on the basis of title. |
catissuecore/rest/groups/title=scg1, this will search for the collection group having title as "scg1"
Response
| Status | Response |
|---|---|
| 200 | application/json |
| 400 | {"error": <any application specific error>} |
| 404 | {"error" : "No group found with title '<title-name>'"} |
| 500 | {"error" : "Something went wrong. please try again later"} |