Page Comparison

Note

This module will not be the preferred REST web service module.

For a more complete list of web service methods see this module's replacement: Webservices.rest Module

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).

...

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
User - get a user by user identifier or name
findUser - get 1 or more patients by user roles, identifier and/or name

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
/moduleServlet/restmodule/api/user/identifierOrName
/moduleServlet/restmodule/json/user/identifierOrName
/moduleServlet/restmodule/api/findUser/identifierOrName?role=RoleName&role=OtherRoleName
/moduleServlet/restmodule/json/findUser/identifierOrName?role=RoleName&role=OtherRoleName

Example Usage

Info
All example URL paths are assumed to start with: http://myhost:myport/openmrs/moduleServlet/restmodule

Example #1: Search for patients matching a search criteria

...

Code Block

	xml
	xml
title	/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>

Code Block

	java
	java
title	/json/findPatient/John


[
  {
    "birthdate": "1975-01-01",
    "birthdateEstimated": "false",
    "gender": "M",
    "identifierList": [
      {
        "preferred": "1",
        "type": "OpenMRS Identification Number",
        "identifier": "100-8"
      },
      {
        "type": "Old Identification Number",
        "identifier": "asdf"
      },
      {
        "type": "Old Identification Number",
        "identifier": "100"
      },
      \
    ],
    "name": {
      "prefix": "pre",
      "givenName": "test123",
      "middleName": "middle",
      "familyName": "test",
      "familyName2": "test2",
      "degree": "deg",

    },
    "addressList": [
      {
        "preferred": "1",
        "address1": "555 Johnson Rd.",
        "address2": "Apt. 555",
        "cityVillage": "Indianapolis",
        "stateProvince": "IN",
        "country": "USA",

      },
      {
        "preferred": "1",
        "address1": "asdf",

      },

    ]
  }
]

...

Code Block

	xml
	xml
title	/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/>
        <cityVillage/>
        <stateProvince/>
        <country/>
      </address>
    </addressList>
  </patient>
</patientList>

Code Block

	java
	java
title	/json/patient/100-3


[
  {
    "birthdate": "1975-01-01",
    "birthdateEstimated": "false",
    "gender": "M",
    "identifierList": [
      {
        "preferred": "1",
        "type": "OpenMRS Identification Number",
        "identifier": "100-8"
      },
      {
        "type": "Old Identification Number",
        "identifier": "asdf"
      },
      {
        "type": "Old Identification Number",
        "identifier": "100"
      },

    ],
    "name": {
      "prefix": "pre",
      "givenName": "test123",
      "middleName": "middle",
      "familyName": "test",
      "familyName2": "test2",
      "degree": "deg",

    },
    "addressList": [
      {
        "preferred": "1",
        "address1": "555 Johnson Rd.",
        "address2": "Apt. 555",
        "cityVillage": "Indianapolis",
        "stateProvince": "IN",
        "country": "USA",

      },
      {
        "preferred": "1",
        "address1": "asdf",

      },

    ]
  }
]

...

Code Block

	xml
	xml
title	/api/obs?pId=100&cId=5090


<?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>

Code Block

	java
	java
title	/json/obs?pId=100&cId=5090


[
  {
    "isObsGrouping": false,
    "patientId": 3,
    "concept": {
      "id": 5090,
      "name": "HEIGHT (CM)"
    },
    "location": {
      "id": 1
    },
    "obsDatetime": "2010-02-15",
    "valueNumeric": 183,
    "isComplex": false,
    "encounter": {
      "id": 1,
      "type": "ADULTINITIAL"
    },
    "uuid": "1b6898bf-bc11-4b79-9f30-8a3c0c4dd10a",
    "comment": "Too tall"
  },
  {
    "isObsGrouping": false,
    "patientId": 3,
    "concept": {
      "id": 5090,
      "name": "HEIGHT (CM)"
    },
    "location": {
      "id": 1
    },
    "obsDatetime": "2010-02-15",
    "valueNumeric": 200,
    "isComplex": false,
    "encounter": {
      "id": 1,
      "type": "ADULTINITIAL"
    },
    "uuid": "1b6808bf-bc17-4b98-9f30-8a3c0c4dd10t",
    "comment": "Too obese"
  }
]

...

Example #4: Sending an hl7 message using rest

http://myhost:serverport/openmrs/moduleServlet/restmodule/api/hl7?message=my_hl7_message_string&source=myHl7SourceName

Example #5: Getting a patient based on the user identifier

Code Block

	xml
	xml
title	/api/user/1


<?xml version="1.0" encoding="UTF-8"?>
<userList version="1.0">
  <user uuid="c6ef8bd8-fd7e-11df-8272-0800271bba91" userId="1" systemId="admin" username="" birthdateEstimated="false" gender="">
    <addressList/>
    <name>
      <givenName>Super</givenName>
      <middleName/>
      <familyName>User</familyName>
    </name>
    <roleList>
      <role>System Developer</role>
      <role>Provider</role>
    </roleList>
  </user>
</userList>

Code Block

	java
	java
title	/json/user/4


[
  {
    "addressList": [],
    "userId": "4",
    "systemId": "4-2",
    "username": "ajanthan",
    "gender": "M",
    "uuid": "c6ef8bd8-fd7e-11df-8272-0800271bba91",
    "name": {
      "givenName": "aja",
      "familyName": "bala"
    },
    "roleList": [
      "System Developer",
      "Provider"
    ]
  }
]

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 setting (formerly global_property table 1.8 and below) table in the database.
Passing connection credentials: ...

Release Notes

1.4.4.2

Added findUser to find users by role, name and/or id
Cleaned up rendering process

...

Versions Compared

Old Version 18

New Version Current

Key

Overview

What This Module Does Do

What This Module Does Not Do

Access URLs

Example Usage

Resources

Tidbits

Release Notes