Web Service 1.0 User Stories

Owned by Ben Wolfe
Last updated: Jul 08, 2011Version comment
2 min read

These were the user stories designed to drive the priorities for the initial release for the Webservices.rest Module while it was being created. See that page for up-to-date documentation

On this page...

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.