Web Service 1.0 User Stories

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

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

    • 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

    • 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

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

  2. Pass the token in the header for all subsequent requests

  3. Logout

    • POST to /ws/rest/logout

    • Invalidates token.