Enhanced Web Services (Design Page)

We need to find out what the convention is for REST-based service when creating objects.  Is a handle for the new object returned in the response?  Or is a redirect used?  We're assuming errors are handled through HTTP error codes +/- response data about the error.

Thought examples:

1. Creating an encounter with observations

REST 1:
* POST to "patient/PATIENT_ID/encounters" with encounter metadata as parameters,
* then repeatedly POST to "patient/PATIENT_ID/encounters/ENCOUNTER_ID/obs"

REST 2: POST to "patient/PATIENT_ID/encounters" with xml the includes encounter metadata and obs

SOAP 1: web method call to createEncounter(EncounterDTO)

SOAP 2:
* web method call to createEncounter(patient, location, date, type)
* then repeated web method calls to createObs(encounter, obsDetails...)

2. Enrolling a patient in a program

REST: POST to "programs/PROGRAM_ID/enrollPatient" with patient=PATIENT_ID&date=DATE
SOAP: web method call to enrollPatientInProgram(patient, program, date)

So, Saptarshi... sitting here in a design conversation with Burke, Ben, and Darius... here are some questions/suggestions for you:

1. There are two ConceptDTO boxes... what do you mean by this?
2. BaseOpenmrsMetadataExtObjectDTO... what's the rationale here?
3. Instead of using ConceptDTO.ConceptClassName, create a new ref object that has a UUID and name attribute... consider calling it MetadataRef or something like this...
4. DTOs for concept_numeric and concept_complex?
5. PersonAddress should extend OpenmrsData
6. ConceptDTO should use OpenmrsMetadata.Name instead of ConceptName
7. PersonAddress and Location should have updated column names consistent with our general move of generalizing them (address 1-6 or whatever it was decided)

Questions for experts:

• Is the model of ws.getPerson(uuid, extraAttributes) a good idea?

Iterating on Ben's last comment (notes here):

Random thoughts and comments

• Ideally we can name the class Concept on the client-side, even though it will probably be ConceptDTO on the server side. (Is this possible?)
• Consider putting the entire web service API under a namespace like "omrs1" for future growth.
• We want to let clients flexibly refer to metadata (e.g. concept datatype) by uuid or name. To support this:
  1. have api methods like getConceptDatatypes(), getConceptNameTypes(), ...
  2. define a flexible "Ref" class with String properties for className, uuid, and a displayable value. You might create a concept by passing datatype="Numeric", but if you fetch a concept, its datatype property is one of these refs:
     Ref example

     concept.datatype ->
     {
         className: "org.openmrs.ConceptDatatype",
         value: "Numeric",
         uuid: "abc123..."
     }
     

Domain Objects

Domain objects have:

• required properties vs. optional properties
• properties that are always fetched vs. properties that are only fetched when requested

CRUD method templates for domain object Xyz

• C: createXyz(requredProp1, requiredProp2, ..., Map optionalProperties)
  • returns persisted Xyz
  • usage: createXyz("req1", "req2", "req3", {"opt1":val1, "opt2":val2});
  • usage: createObs(personUuid, datetime, questionUuid, value, {"location": "Rwinkwavu"});
  • optionalProperties is a Map from (String) property name to property value
• R: getXyz("uuid or unique name", List extraProperties)
  • returns Xyz
  • metadata may also be fetched by its unique name
  • data can only be fetched by its uuid
  • extraProperties is a List of (String) property names which would otherwise be null on the returned object
  • other retrieval methods depend on the specific domain object
• U: updateXyz("uuid or unique name", Map propertiesToValues)
  • returns updated Xyz
  • only the specified properties of the object are updated to the new values
  • does not work for collection properties
• D: retireXyz("uuid or unique name", "reason for retiring")
  • returns retired xyz
  • for metadata like concept, location, encounterType
  • marks the object as inactive
• D: deleteXyz("uuid", "reason for deleting")
  • returns deleted xyz
  • for data like patient, obs, encounter
  • marks the object as voided (but I think "deleted" is clearer for the client)
• X: purgeXyz("uuid")
  • returns nothing
  • maybe this should require a secret token as a second argument
  • deletes the object from the database
  • fails if the object is in use

Concept, as a fully-worked example

Concept Properties

// required for creation
Ref datatype
Ref conceptClass
String name // primary name
String locale // locale of primary name

// always returned (in addition to above)
String uuid
boolean retired

// optional (null unless requested)
String description
AuditInfo auditInfo
List<ConceptName> names
List<ConceptName> shortNames
List<ConceptDescription> descriptions
List<Concept> setMembers
List<ConceptAnswer> answers

// intentionally not exposed: conceptId, isSet, version

Ref creator
Date dateCreated
Ref changedBy
Date dateChanged
Ref retiredBy
Date dateRetired
String retireReason
Ref voidedBy
Date dateVoided
String voidReason

//properties
String answerType // "concept", "drug", "conceptSet", or "conceptClass"
Ref answer

// currently answers are only allowed to be concept or drug, but we want to be future-proof
// example usage
if (question.answers[0].answerType == "set") {
    Concept[] members = api.getConceptSetMembers(question.answers[0].answer.uuid);
    // do something with each
}

Standard CRUD, applied to Concept

• C: c = api.createConcept("Numeric", "Test", "HEMOGLOBIN", "en", {description: ""Stuff in the blood..."});
• R: c = api.getConcept("HEMOGLOBIN", null);
• U: c = api.updateConcept(c.uuid, {"conceptClass": "Symptom"});
• D: c = api.retireConcept(c.uuid, "because");
• X: api.purgeConcept(c.uuid)

Other retrieval methods:

• Concept[] findConcepts("partial name", "locale", [extraProperties]) // fuzzy/partial name search
• Concept[] findConcepts("partial name", datatype, conceptClass, [extraProperties])
  • Ben will say we should name these two getConceptsByName
• Concept getConceptByFullySpecifiedName("fully specified name", "locale", [extraProperties])
• Concept[] getConceptSetMembers(setUuid, [extraProperties])
• ConceptAnswer[] getConceptAnswers(questionUuid, [extraProperties])
• Concept[] getConceptsByMapping(source, code, [extraProperties])

Collection properties of Concept

Concept names

• addNameToConcept(c.uuid, "a name", "en_US", preferred, type="fully-specified", {optionalNameProperties})
  • On the topic of "addConceptName" vs. "addNameToConcept" choice for method names: since we are already grouping by function (i.e., "add"), then the "addNameToConcept" approach further groups by function groupings AND reads better.
• removeNameFromConcept(conceptNameUuid)
• removeNameFromConcept(conceptUuid, "a name", "en_US")
  • both these methods void the name. They fail if it's the only name, removing fully specified name, etc.
• addShortNameToConcept(...)
• removeShortNameFromConcept(...) x2
  • same options as addNameToConcept/removeNameFromConcept. The point is that short name is a separate property, not an alternate name
    Edit an existing name

    ConceptName cn = something ; // somehow get this from the API
    api.updateConceptName(cn, {name: "Cough", "localePreferred", true});
    

Concept set members needs work

• addMemberToSet(setUuid, memberUuid, beforeMemberUuid)
  • assigns isSet=true on the set if not already specified
  • beforeMemberUuid is nullable.  if null, memberUuid is at the end of the list
• setMembersOnSet(setUuid, [memberUuids])
  • Replaces all with the given order? 
  • Rename this method?
• removeMemberFromSet(setUuid, memberUuid)

Concept subclasses (ConceptNumeric, ConceptComplex)

Question for the experts: which path to take for Concept subclasses?

1. ConceptNumeric extends Concept (and includes range, units, and precision properties)
2. ConceptNumeric includes a Concept property (and also range, units, and precision properties)
3. just have Concept, which has range, units, and precision as optional properties