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

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.