OpenMRS: Rework API (WIP)

[josephjclark]

New major release of OpenMRS API.

No callbacks (use .then() or fn()) instead

Phase 1: Add generic HTTP request

Add a totally generic HTTP request method, like in http.

http.request(method, path, options)

Where options is { query, headers, body }. Body is a JSON payload. Note that there is no callback.

The path is relative to the base URL in config. Do not prefix ws/rest/v1 or anything like that.

I presume that all data is JSON by default. Is there any non-JSON data we want to upload and download?

If it does not already exist, there should be an underlying util.request() function which uses common http. Alternatively, consider importing the http adaptor and wrapping its functions (or exposing them directly). If we do this I am happy to support the callback.

request() should write the result to state.data and should also write a state.response (just like http does)

Note that this needs adding to the http namespace - you'll need to create a http.js file with all the HTTP namespaced code in.

Phase 2: Add other HTTP helpers

Extend the HTTP namespace with http,get(), http.post() and http.delete() helpers. These are just like the regular http adaptor functions. Consider exporting the http functions directly.

Phase 3: Add rest API helpers

In the main namespace we should add (or change) functions which call out to the rest API directly

get(resource, options)

Where options is { id, q, query, limit, subresource }

• q and query are aliases and map directly to query parameters
• subresource is appended to the end of the path, ie, patient/:id/allery. Alias to sub.

Resource should accept a path, like patient/1235

Note that if resource is not a path, and no query is provided (ie, get('patient'), I think we have to default q to all

This function should append ws/rest/v{version} to all paths

We should also add the following helpers:

create(resourceType, data, options)
update(resourceType, resourceId, data, options)
upsert(resourceType, resourceId, data, options)
delete(resourceType, resourceId, options)

Where options are appended to the URL as query parameters. Except subresource or sub, which is added to the URL, like patient/:target_patient_uuid/allergy

Question: Should we support a path or just id? Ie, update('patient', 'abdc/allergy') vs update('patient', 'abdc', { sub: 'allergy')? I prefer sub because resourceId is a better argument name than resourceIdOrPath

Phase 4: Clean up other APIs

• remove getEncounter, getEncounters, getPatient, searchPatient and searchPerson (all are served by get())

Phase 5: Add fully-featured fhir namespace

Add a fhir namespace, if, fhir.get()

We should only do this when we have the new fhir-4 adaptor.

We should reference and re-export standard fhir-4 functions, rather than re-writing them ourselves.