Some ideas based on how our API would look like if it is designed them from its user’s point of view and not from how the data is organised in the system. I haven’t thought through everything in minutest details yet, but following is the outline.
Resources
Some of the following are sub-resources, i.e. they can be contained inside another resource. For example - treatments can be accessed directly or they get embedded inside an encounter.
Patient Profiles
Visits
This doesn't contain the encounters. It would be good to have references to encounters inside it. Is OpenMRS resource sufficient for this?
Clinical Encounters
It should de-normalize the visit dates on the encounter. Probably an href to the visit.
Diagnoses
Lab Investigations
It contains lab order, sample accession and lab result. If we find this resource to be too big then we would break it down into further sub-resources. Right now we do not know how exactly it would pan out when we do the OpenELIS replace work.
Procedures
Observations
It is only a subset of OpenMRS observations excluding procedures, lab-results, or anything which its own resource. This filtering should be done by the server endpoint. The API should also handle different classes differently making it easier for the consumer to consume it. The observation classes which Bahmni supports right now are "Qualified with Duration", "Qualified with Normality", "Multiple Coded" (better names are welcome).
Treatments
Drug order and treatment related observations. Also supports a special operation called "active".
Clinical Images
A sub-resource and not an attribute because of performance reasons.
Enrolled Programs
We would be using programs for chronic patients. Contains href for encounters inside it.
Meta Resources (aka reference data)
Programs
Visit Types
Patient Attributes
Lab Tests
Lab Test Panels
Lab Departments
Diagnosis Types
Reference Terms
Observation Type Groups
This exposes different aggregate observation classes (see observations resource) differently, making it easier for the consumer. I haven't been able to find any use case for which a concept would have to be directly exposed via an api.
Procedure Types
Locations
Address Elements
Ways to break up patient data
Scope of resources
Visit, Date, Encounter, All
For (Keywords that Bahmni could support. This would help in reducing unnecessary calls to find what their id is. The current list is below.)
LastVisit
LastVisitFoundIn
CurrentEncounter
CurrentVisit
All (default)
Initial (In Visit)
Most Recent (In Visit)
Internal or technical resources (haven’t given much thought to these yet)
SqlSearch
Scheduled Tasks
Design
- The concepts which are always packaged with Bahmni should be referred by their name not by UUID. For example - consultation note, radiology notes (when doctor makes observation on an image).
- There is no need to expose encounter types and order types. These should just be the internals for Bahmni.
- Use hyperlinks when referencing meta resources but not sub-resources. The performance issues arising of loading too much data can be taken care of by loading the sub-resources directly and using the scope keywords.
- User transaction should result in single save call to the server unless there is a performance reasons to not do so.
- Ideally any save operation should not require the client to make read calls (for getting id etc.) for populating the data in the request.
Examples
/patient-profiles/<patient-id>
/diagnoses?patient-id=<patient-id>
/observations?observation-type=vitals
/treatments?patient-id=<patient-id>&for=last-visit
/encounters?for=current
/encounters?for=current-visit
/visits
Links
http://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf
Notes from meeting
How to handle concept-answers vs. answers coming from different concept set. Concept answers can be returned along with observation type group resource. When the answers in a different concept-set we probably just need to perform a search on it, need not expose the complete list via the api.
Define the scoping parameters for various resources.
Is there a case for LastEncFound keyword? (suggestion made to call it most recent or just recent in the context of BMI) MostRecent[Observation].
How would we handle validation of test results?
What about bed management? Location?
Is this API sufficient for reports to get all the data it needs?
The example above doesn't use patient-id everywhere it should
Should observation type groups be called form?