Common Lab Module Rest API

Owned by Tahira Niazi
Last updated: Jan 21, 2019

Overview

This is the technical documentation for REST component of Common Lab Module. General information and user documentation for the module can be found here.

Resources

Create Lab Test Order

Lab Test contains a mandatory Order object, which is abstract OpenMRS object used for Lab Test and Drug orders. Therefore, order object will also be created. Whereas, Orderer property hold uuid for Provider object.

POST Lab Test
POST ws/rest/v1/commonlab/labtestorder
Body Content:
{
  "labReferenceNumber": "ESR - 2019-01-21 12:23:14",
  "labTestType": "4f4c97c8-61c3-4c4e-82bc-ef3e8abe8ffa",
  "order": {
    "action": "NEW",
    "patient": "e0c73f96-eab9-4cd0-95b5-c656ca9920b6",
    "concept": "dcd97733-4262-4947-ac69-fd2d00880803",
    "encounter": "9e10fab4-a69d-4726-8f14-531f0b9ee0fc",
    "careSetting": "6f0c9a92-6f24-11e3-af88-005056821db0",
    "type": "testorder",
    "orderer": "0e5ac8a2-cb48-40ff-a9bd-b0e09afa7860"
  }
}

Create Lab Test Sample

For creating Lab Test Sample, Lab Test uuid is attached in json as it contains a reference to Lab Test entity. Collector property holds Provider uuid.

POST Lab Test Sample
POST ws/rest/v1/commonlab/labtestsample
Body Content:
{
	"labTest": "b164ad70-ca92-4bc0-b87c-f7fe79a365f3",	
    "specimenType": "1000AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "specimenSite": "161939AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "sampleIdentifier": "sample-12345",
    "collectionDate": "2019-01-21 00:00:08",
    "status": "COLLECTED",
    "collector": "0e5ac8a2-cb48-40ff-a9bd-b0e09afa7860"
}

Submit Test Result (Create Lab Test Attributes)

For each Lab Test, result mostly contains multiple Lab Test Attributes therefore, an array will be attached in json with the associated Order uuid (labReferenceNumber and labTestType are required properties).

POST Lab Test Attributes
POST ws/rest/v1/commonlab/labtestorder
Body Content:
{
  "order": "7494b8a1-27f3-4c98-9116-3206819c9b67",
  "labReferenceNumber": "ultrasound-2018-09-26 18:31:09.031",
  "labTestType": "c0f8614f-57aa-4341-9920-86e2d6d1e607",
  "attributes": [
    {
      "attributeType": "04a8fd90-d6d6-4554-9100-944e65646dac",
      "valueReference": "NORMAL"
    }
  ]
}

Create Lab Test order & Sample in single request

Lab Test order and sample can be created together in a single request as follows.

POST Lab Test & Sample in single request
POST ws/rest/v1/commonlab/labtestorder
Body Content:
{
  "labReferenceNumber": "QFT - 2019-01-21 12:23:14",
  "labTestType": "4f4c97c8-61c3-4c4e-82bc-ef3e8abe8ffa",
  "order": {
    "action": "NEW",
    "patient": "e0c73f96-eab9-4cd0-95b5-c656ca9920b6",
    "concept": "dcd97733-4262-4947-ac69-fd2d00880803",
    "encounter": "9e10fab4-a69d-4726-8f14-531f0b9ee0fc",
    "careSetting": "6f0c9a92-6f24-11e3-af88-005056821db0",
    "type": "testorder",
    "orderer": "0e5ac8a2-cb48-40ff-a9bd-b0e09afa7860"
  },
  "labTestSamples": [
    {
      "specimenType": "1000AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "specimenSite": "161939AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "collectionDate": "2019-01-21 00:00:08",
      "status": "COLLECTED",
      "collector": "0e5ac8a2-cb48-40ff-a9bd-b0e09afa7860",
      "labTest": "b164ad70-ca92-4bc0-b87c-f7fe79a365f3"
    }
  ]
}

Create Lab Test order, Sample & Results in single request

We can create Lab Test order, sample & results in single request. This is useful in case we have all information from test order phase to results declaration. It can be done as follows.

POST Lab Test Order, Sample, Lab Results in single request
POST ws/rest/v1/commonlab/labtestorder
Body Content:
{
  "labReferenceNumber": "QFT - 2019-01-21 12:23:14",
  "labTestType": "4f4c97c8-61c3-4c4e-82bc-ef3e8abe8ffa",
  "labTestSamples": [
    {
      "specimenType": "1000AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "specimenSite": "161939AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "collectionDate": "2019-01-21 00:00:08",
      "status": "COLLECTED",
      "collector": "0e5ac8a2-cb48-40ff-a9bd-b0e09afa7860",
      "labTest": "b164ad70-ca92-4bc0-b87c-f7fe79a365f3"
    }
  ],
  "order": {
    "action": "NEW",
    "patient": "e0c73f96-eab9-4cd0-95b5-c656ca9920b6",
    "concept": "dcd97733-4262-4947-ac69-fd2d00880803",
    "encounter": "9e10fab4-a69d-4726-8f14-531f0b9ee0fc",
    "careSetting": "6f0c9a92-6f24-11e3-af88-005056821db0",
    "type": "testorder",
    "orderer": "0e5ac8a2-cb48-40ff-a9bd-b0e09afa7860"
  },
  "attributes": [
    {
      "attributeType": "04a8fd90-d6d6-4554-9100-944e65646dac",
      "valueReference": "NORMAL"
    }
  ]
}

Void Data

Data can be void via REST request by using DELETE. 

Void data
DELETE ws/rest/v1/commonlab/labtestsample/9927cef4-e9c8-4fb3-83ce-2e05f85d5897