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
On this page...
Show a patient summary
Fetch a patient, their encounters, and their observations.
- 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 }
- 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
- or
- 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.
- 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)
- 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.
- Search for cohorts by name
GET /ws/rest/cohort?name=
partialname
- Get cohort by uuid
GET /ws/rest/cohort/
cohortsuuid
Data entry from a mobile device
- Search a patient
GET /ws/rest/patient?q=123MT-2
GET /ws/rest/patient?q=Joe+Bob
- Fetch past encounters for patient
GET /ws/rest/encounter?patient=
uuid-of-patient
- Add a new encounter
POST /ws/rest/encounter
- content is json key/value pairs
External lab system needs to submit lab results to OpenMRS
- Search locations
GET /ws/rest/location?name=MTRH
- Search patients by name and/or identifier
- (see above)
New OpenMRS admin wants to import some old encounter data into OpenMRS
- Add patient
POST to /ws/rest/patient
- content is json key/value pairs
- Add a new encounter
- See above
Submitting HL7 messages to the HL7 inbound queue
- 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.
- Request token
POST to /ws/rest/login
- Use HTTP Digest of username and password
- Response from POST
{ token: "af3je3jkLm7" }
- Pass the token in the header for all subsequent requests
- Logout
-
POST to /ws/rest/logout
- Invalidates token.
-