All OpenMRS ID accounts have been reset.

Read more and change your password before signing in.
Icon

EXTENDED: OMRS14 Proposals due 30 April! Read more and submit a proposal at OpenMRS Talk.

Skip to end of metadata
Go to start of metadata
Icon

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
      {
      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.
  • No labels

8 Comments

  1. For the default patient representation, I think we want to include known identifiers and I don't think a "ref" will suffice, since you need to know the type for each identifier as well as which is preferred.

    1. I'd rather we have the preferred identifier/identifierType a property by default with a list of Refs of all identifiers.  If the user wants to know all identifiers+types with one query, they can ask for rep="default,custom(identifiers.identifier, identifiers.identifierType)" and get back objects that have identifier strings and Ref IdentifierTypes.

  2. When representing encounters, we have to decide on the default representation of observations.

    Encounters with obs as refs
    Encounters with simple obs representation by default
    1. What about doing neither unless the user puts it in the representation as Darius suggests?  I like that solution more than creating some sort of medium sized object.

    • In the get patient by identifier example, the identifier should not be a Ref, but the identifier.identifierType should be.
    • I think that if you are fetching more than one encounter, you should never get the obs back. If you're fetching a single encounter, you do get the obs (exploded) by default.
      • so I think your default rep for "get last 10 encounters for patient" should not include obs or orders
    1. (made your suggested changes in the page and removed them from your comment, so as to not confuse people later on)

  3. Let's get that 0.1 module out the door, backwards-compatible with 1.8.0!

    1. It won't be compatible with 1.8.0, only 1.8.1 at best. There were changes we had to make to trunk in order for services to be registered, bug fixes, etc. Those were too late in the 1.8.0 release cycle to be included safely. We are working on backporting those fixes from trunk to the 1.8.x line now and the module will be released with that minimum dependency.