Overview
What This Module Does Do
The OpenMRS REST Module provides a limited mechanism for communicating with an OpenMRS system externally as a client via Web Services. In this case, the REST Module is implemented using REST (1).
The methods or functions currently exposed via the OpenMRS REST Module are as follows:
- patient - get 1 or more patients by patient identifier
- findPatient - get 1 or more patients by patient name
- Observations - get a list of observation by submitting the patient identifier and concept id
- Submitting an hl7 message - send the hl7 source name and hl7 message string via the HTTP PUT method
What This Module Does Not Do
Here's some caveats to usage of the REST Module:
- REST is not SOAP - If you need SOAP, you'll need to write a SOAP layer on top of this module, or convert your SOAP calls to REST in your client
- The entire OpenMRS API is not exposed here -- hopefully more of the API is exposed as time goes on
- Calls to the API are not Audited (as far as I can tell)
Access URLs
- /moduleServlet/restmodule/api/findPatient/
- /moduleServlet/restmodule/json/findPatient/
- /moduleServlet/restmodule/api/patient
- /moduleServlet/restmodule/json/patient
- /moduleServlet/restmodule/api/hl7
- /moduleServlet/restmodule/api/obs?pId=patientIdentifier&cId=conceptId
- /moduleServlet/restmodule/json/obs?pId=patientIdentifier&cId=conceptId
Example Usage
Example #1: Search for patients matching a search criteria
This call would do a Patient Query based on the search string "John Smith". A list of patients matching that search criteria would be returned.
http://myhost:myport/openmrs/moduleServlet/restmodule/api/findPatient/John+Smith
<patientList><patient birthdate="1975-01-01" birthdateEstimated="false" gender="M"><identifierList><identifier preferred="1" type="OpenMRS Identification Number">100-8</identifier><identifier type="Old Identification Number">asdf</identifier><identifier type="Old Identification Number">100</identifier></identifierList><name><prefix>pre</prefix><givenName>test123</givenName><middleName>middle</middleName><familyName>test</familyName><familyName2>test2</familyName2><degree>deg</degree></name><addressList><address preferred="1"><address1>555 Johnson Rd.</address1><address2>Apt. 555</address2><cityVillage>Indianapolis</cityVillage><stateProvince>IN</stateProvince><country>USA</country></address><address preferred="1"><address1>asdf</address1><address2></address2><cityVillage></cityVillage><stateProvince></stateProvince><country></country></address></addressList></patient></patientList>
http://myhost:myport/openmrs/moduleServlet/restmodule/json/findPatient/John
[
]
Example #2:
This call does a Patient Lookup based on the OpenMRS Identifier "OpenMRS Identification Number". In this case, the Patient with the ID Number of "100-3" would be returned.
http://myhost:myport/openmrs/moduleServlet/restmodule/api/patient/100-3
<patientList><patient birthdate="1975-01-01" birthdateEstimated="false" gender="M"><identifierList><identifier preferred="1" type="OpenMRS Identification Number">100-8</identifier><identifier type="Old Identification Number">asdf</identifier><identifier type="Old Identification Number">100</identifier></identifierList><name><prefix>pre</prefix><givenName>test123</givenName><middleName>middle</middleName><familyName>test</familyName><familyName2>test2</familyName2><degree>deg</degree></name><addressList><address preferred="1"><address1>555 Johnson Rd.</address1><address2>Apt. 555</address2><cityVillage>Indianapolis</cityVillage><stateProvince>IN</stateProvince><country>USA</country></address><address preferred="1"><address1>asdf</address1><address2></address2><cityVillage></cityVillage><stateProvince></stateProvince><country></country></address></addressList></patient></patientList>
http://myhost:myport/openmrs/moduleServlet/restmodule/json/patient/100-3
[
]
Example #3: Request for a list of observations for a given patient and concept
URL for XML: http://myhost:myport/openmrs/moduleServlet/restmodule/api/obs?pId=100&cId=5090
Output (XML):<?xml version="1.0" encoding="UTF-8"?>
<obsList version="1.0">
<obs uuid="1b6898bf-bc11-4b79-9f30-8a3c0c4dd10a" patientId="3" obsDatetime="2010-02-15" isObsGrouping="false" isComplex="false">
<concept id="5090">HEIGHT (CM)</concept>
<valueNumeric>183.0</valueNumeric>
<encounter id="1" type="ADULTINITIAL"/>
<comment>Too tall</comment>
<location id="1"/>
</obs>
<obs uuid="1b6808bf-bc17-4b98-9f30-8a3c0c4dd10t" patientId="3" obsDatetime="2010-02-15" isObsGrouping="false" isComplex="false">
<concept id="5090">HEIGHT (CM)</concept>
<valueNumeric>200.0</valueNumeric>
<encounter id="1" type="ADULTINITIAL"/>
<comment>Too obese</comment>
<location id="1"/>
</obs>
</obsList>
URL for JSON: http://myhost:myport/openmrs/moduleServlet/restmodule/json/obs?pId=100&cId=5090
Output (JSON):[
{
"isObsGrouping": false,
"patientId": 3,
"concept":
,
"location":
,
"obsDatetime": "2010-02-15",
"valueNumeric": 183,
"isComplex": false,
"encounter":
,
"uuid": "1b6898bf-bc11-4b79-9f30-8a3c0c4dd10a",
"comment": "Too tall"
},
{
"isObsGrouping": false,
"patientId": 3,
"concept":
,
"location":
,
"obsDatetime": "2010-02-15",
"valueNumeric": 200,
"isComplex": false,
"encounter":
,
"uuid": "1b6808bf-bc17-4b98-9f30-8a3c0c4dd10t",
"comment": "Too obese"
}
]
Note: The parameters at the end of the request URL i.e pId and cId are patientId and conceptId respectively. If you wish to view the JSON output in your browser, you will need to install a json viewer plugin for your respective browser if it exists, otherwise you will be prompted to save the file.
Example #4: Sending an hl7 message using rest
Resources
Tidbits
- Calls to the REST library are restricted by the IP source address of the calling client. By default, this IP list is limited to calls from localhost (127.0.0.1). If you want to modify this list to allow other clients to call the REST layer, simply update the appropriate property in the global_property table in the database.
- Passing connection credentials: ...
Release Notes
0.5
- Remarks have been extended to the patient dashboard and encounter form