caTissue REST API
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 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 |
| 401 | All requests | Authorization failed |
| 403 | All requests | |
| 404 | All requests | Resource not found |
| 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.
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} |
| 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"} |
| 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"} |
| 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
| Status | Response |
|---|---|
| 200 | application/json |
| 404 | {"error" : "No group found with title '<title-name>'"} |
| 500 | {"error" : "Something went wrong. please try again later"} |