Page Comparison

...

• Create: POST /ws/rest/patient
  • success: 201 CREATED with Location: "uri-of-created-resource", content: default representation of created object
  • failure: 400 or 500
• Search: GET /ws/rest/patient?q=name+or+identifier
  • success: 200 OK with a list of minimal patient representations as content
  • failure: not really possible
• Retrieve: GET /ws/rest/patient/uuid.json
  • success: 200 OK with content: default json representation of patient
  • no patient found for given uuid: 404 NOT FOUND
• Retrieve: GET /ws/rest/patient/uuid.json?v=full
  • like above, but a "full" representation (e.g. also containing a list of encounters)
• Update: POST /ws/rest/patient/uuid with the request content the properties we want to change on the object
  • e.g. to change a patient's birthdate you'd POST { "birthdate": "1978-05-24", "birthdateEstimated": false }
  • does this seem okay, rather than using PUT with the complete object?
  • success: 204 NO CONTENT
  • no patient found for given uuid: 404 NOT FOUND
  • failure: 400 or 500
• Soft Delete: DELETE /ws/rest/patient/uuid
  • this actually means "mark deleted" in OpenMRS
  "Delete forever"
  • success: 204 NO CONTENT (includes the case where the patient is already voided)
  • no patient found for given uuid: 404 NOT FOUND
  • failure: 400 or 500
• Hard Delete: DELETE /ws/rest/patient/uuid?purge=true
  • actually deletes an entity from the database
  • is there a better way to indicate this special, rarely-used method?
  • success: 204 NO CONTENT
  • no patient found for given uuid: 204 NO CONTENT (treat as success, because DELETE is idempotent)
  • failure: 400 or 500 (depending on whether it's an APIException)

Our domain objects are often large (a patient and all their encounters and clinical observations), and contain lots of rarely-interesting book-keeping information (creator, date created, etc), and we expect many clients to be bandwidth-limited. Therefore we want to allow clients to fetch different representations of a any resource. For example you could get a "default" patient representation (:

• /ws/rest/patient/uuid.json -> default representation, only including the patient's preferred name, not including audit info

...

• /ws/rest/patient/uuid.json?v=full -> representaion including all their names, all audit info, etc

...

• /ws/rest/patient/uuid.json?v=fullwithencounters -> full representation plus summaries of all the patient's encounters (this is big)
  Is this appropriate? If so, what's the right terminology for this? If not, what alternate approach should we be taking?

We also introduce the idea of a "Ref", which is a minimal representation of any object, just containing its uuid, a displayable string, and a URI link to the full resource. So for example if I fetch the default representation of a patient, I might get this:

{
  "personAddress" : {
    "uuid" : "3350d0b5-821c-4e5e-ad1d-a9bce331e118",
    "display" : "1050 Wishard Blvd., RG5, Indianapolis, IN",
    "uri" : "http://.../ws/rest/personaddress/3350d0b5-821c-4e5e-ad1d-a9bce331e118"
  },
 
/\* more stuff \*/
}

Whereas if I fetch the full representation of a patient I might get:

{
 
"personAddress" : {
    "uuid" : "3350d0b5-821c-4e5e-ad1d-a9bce331e118",
    "address1" : "1050 Wishard Blvd.",
    "address2" : "RG5",
    "cityVillage" : "Indianapolis",
    "stateProvince" : "IN",
    "uri" : "http://.../ws/rest/personaddress/3350d0b5-821c-4e5e-ad1d-a9bce331e118"
  },
 
/\* more stuff \*/
}

A more relevant example of this is that an encounter might contain 100 observations. The default encounter representation would just include a displayable "weight = 70", whereas the full encounter representation would include full details about the "weight" question (e.g. that it's unit is "kg", its range is 0-250, etc).

...

Does this sound right?

Authentication

...

We assume this will be straightforward once we sit down to design and implement it, and we should be worried about thisit (though probably annoying to implement). Any words of warning? Any examples we should look at or obvious technology terms to search for?

...