Web Service 1.0 User Stories

Show a patient summary

Fetch a patient, their encounters, and their observations.

1. Find a patient by identifier
   • GET /ws/rest/patient?q=123MT2
   • Representation: default
   • JSON Return Value

     {
     uuid: "1AA43D-324-AFE8349AC",
     uri: "https://foo.com/ws/rest/patient/1AA43D-324-AFE8349AC",
     display: "John A. Doe (93498309234)",
     name: "John A. Doe",
     identifier: 9349,
     identifierType: { display: "Hospital X Identifier Number", uuid: "342834239234",
     identifiers:
     [
     {display: "9349 (Hospital X Identification Number)", uuid: "00AF-55-111", uri: "https://foo.com/openmrs/ws/rest/patient/1AA43D-324-AFE8349AC/identifier/00AF-55-111"},{display: "AA-4 (Hospital Y Id Number", uuid: "123", uri: "https://foo.com/openmrs/ws/rest/patient/1AA43D-324-AFE8349AC/identifier/123"}
     ]
     gender: "M",
     birthdate: "1955-05-25",
     voided: false,
     dead: false
     }
     

2. Get last 10 encounters for patient
   • GET /ws/rest/encounter?patient=1AA43D-324-AFE8349AC&limit=10
     • or GET /ws/rest/patient/1AA43D-324-AFE8349AC/encounters?limit=10
   • Representation: default
   • JSON Return Value

     [
     {
     uuid: "029434-AA-32EE",
     uri: "https://foo.com/ws/rest/encounter/029434-AA-32EE",
     display: "Adult Return Hospital X
     encounterDatetime: "2000-05-25 14:05:03",
     patient: { display: "John A. Doe (123-0)", uuid: "1AA43D-324-AFE8349AC", uri: "https://foo.com/openmrs/ws/rest/patient/1AA43D-324-AFE8349AC" },
     location: { display: "Hospital X", uuid: "39209-324-999", uri: "https://foo.com/openmrs/ws/rest/location/39209-324-999" },
     form: { display: "Outpatient Form", uuid: "F23BCA-324-22", uri: "https://foo.com/openmrs/ws/rest/form/F23BCA-324-22" },
     encounterType: { display: "Adult Return", uuid: "123CA-324-22", uri: "https://foo.com/openmrs/ws/rest/encountertype/123CA-324-22" },
     provider: { display: "Susan B Anthony (6400-6)", uuid: "392A-324-111", uri: "https://foo.com/openmrs/ws/rest/provider/392A-324-111" },
     obs:
     [
     { display: "WEIGHT (KG) = 70", uuid: "BBB-324-111", uri: "https://foo.com/openmrs/ws/rest/obs/BBB-324-111" },{ display: "TRANSPORTATION METHOD = VELOCIRAPTOR", uuid: "0019-324-111", uri: "https://foo.com/openmrs/ws/rest/obs/0019-324-111" }
     ]
     },
     orders:
     [{ ... },
     { ... }
     ]
     },
     {
     encounterDatetime: ...
     ...
     }
     ]
     

   • Representation: partial
   • JSON Return Value

     [
     {
     uuid: "029434-AA-32EE",
     uri: "https://foo.com/ws/rest/encounter/029434-AA-32EE",
     display: "Adult Return Hospital X
     encounterDatetime: "2000-05-25 14:05:03",
     patient: {
       display: "John A. Doe (123-0)",
       uuid: "1AA43D-324-AFE8349AC",
       uri: "https://foo.com/openmrs/ws/rest/patient/1AA43D-324-AFE8349AC" },
     name: "John A Doe",
     identifier: "123-0",
     identifierType: "asdf",
     identifiers { (list of identifier refs) },
     },
     location: { display: "Hospital X", uuid: "39209-324-999", uri: "https://foo.com/openmrs/ws/rest/location/39209-324-999" },
     form: { display: "Outpatient Form", uuid: "F23BCA-324-22", uri: "https://foo.com/openmrs/ws/rest/form/F23BCA-324-22" },
     encounterType: { display: "Adult Return", uuid: "123CA-324-22", uri: "https://foo.com/openmrs/ws/rest/encountertype/123CA-324-22" },
     provider: { display: "Susan B Anthony (6400-6)", uuid: "392A-324-111", uri: "https://foo.com/openmrs/ws/rest/provider/392A-324-111" },
     obs:
     [
     { display: "WEIGHT (KG) = 70", uuid: "BBB-324-111", uri: "https://foo.com/openmrs/ws/rest/obs/BBB-324-111" },{ display: "TRANSPORTATION METHOD = VELOCIRAPTOR", uuid: "0019-324-111", uri: "https://foo.com/openmrs/ws/rest/obs/0019-324-111" }
     ]
     },
     orders:
     [{ ... },
     { ... }
     ]
     },
     {
     uuid: ,
     display: ,
     uuid: ,
     encounterDatetime: ...
     ...
     }
     ]
     

Create a new encounter, or edit an existing encounter

In this story, the client could be a form entry tool.

1. Create an encounter and observations in one swoop
   • POST /ws/rest/encounter
   • POST Request post content

     {
     encounterDatetime: "2000-05-25 14:05:03",
     patient: "1AA43D-324-AFE8349AC",
     location: "Hospital X",
     form: "F23BCA-324-22",
     encounterType: "123CA-324-22",
     provider: "392A-324-111",
     obs:
     [
     { question="034892-AA-3248", answer="70" },{ question="034892-AA-3248", answer="222-EE-222" }
     ]
     }
     

   • Returns back a default representation of the encounter (as shown in previous use case)
2. Edit an encounter metadata
   • PUT /ws/rest/encounter/029434-AA-32EE
   • POST Request post content

     {
     encounterDatetime: "2000-05-26 14:05:03",
     location: "Hospital Y"
     }
     

   • Returns back a default representation of the encounter (as shown in previous previous use case)

See what patients are in a named cohort

A counselor in the field using a mobile device needs to review a list of patients to be interviewed.

1. Search for cohorts by name
   • GET /ws/rest/cohort?name=partialname
2. Get cohort by uuid
   • GET /ws/rest/cohort/cohortsuuid

Data entry from a mobile device

1. Search a patient
   • GET /ws/rest/patient?q=123MT-2
   • GET /ws/rest/patient?q=Joe+Bob
2. Fetch past encounters for patient
   • GET /ws/rest/encounter?patient=uuid-of-patient
3. Add a new encounter
   • POST /ws/rest/encounter
     • content is json key/value pairs

External lab system needs to submit lab results to OpenMRS

1. Search locations
   • GET /ws/rest/location?name=MTRH
2. Search patients by name and/or identifier
   • (see above)

New OpenMRS admin wants to import some old encounter data into OpenMRS

1. Add patient
   • POST to /ws/rest/patient
     • content is json key/value pairs
2. Add a new encounter
   • See above

Submitting HL7 messages to the HL7 inbound queue

1. Insert hl7 into hl7_in_queue
   • POST to /ws/rest/hl7
   • POST Request post content

     {
     message: "KLJSDF||||SDF|S|DF|||||S|DF|S|F"
     }
     

Authentication

In all cases, the client will need to authenticate before it can access the resources.

1. Request token
   • POST to /ws/rest/login
   • Use HTTP Digest of username and password
   • Response from POST

     {
     token: "af3je3jkLm7"
     }

2. Pass the token in the header for all subsequent requests
3. Logout
   • POST to /ws/rest/logout
   • Invalidates token.