API implementation levels

[ErikSundvall]

Background:

See discussion at https://openehr.atlassian.net/wiki/display/spec/openEHR+REST+APIs

It can be hard for some implementers to support all kinds of calls, we could provide a well specified conformance ladder with basic levels that are easy to add but still are very useful for integrations. Defining R1+W1+Q1 should probably be first priority timewise.

Implementation levels (an initial suggestion)

• R1 Basic read-only. COMPOSITION+FOLDER listing and retrieval.
• R2 Level 2 read-only. R1 as above plus: Support for listing and retrieval of CONTRIBUTIONS, EHR_STATUS and EHR_ACCESS...
• W1 Basic write. Writing/updating COMPOSITIONS one by one. Creating new EHRs...
• W2 Level 2 write. W1 as above plus Writing several changes at once using a CONTRIBUTION...
• W3 Level 3 write. W2 as above plus multi-EHR-spanning-commit mechanism (allowing Atomic correction moves etc between different EHRs)
• QL1 Basic Query...
• QL2 Level 2 Query. Named/identified queries with dynamic parameters (allows stored procedures and other optimizations).
• CDS1...? Clinical Decision Support?

One system could for example support R1+QL1 another might support R2+W2

Suggested next steps

1. Discuss suitable levels
2. add short text about levels in Apiary intro text (and refer/link to related spec-document for more reasoning about levels)
3. add a level marker, e.g. "(Api Level R1)" to the description text of suitable resources/calls

I (@ErikSundvall) can make some initial changes to the file to illustrate and get started, then initiate a pull request.

[bostjanl]

How about we just do the first API definition with just the calls we really have to support to be called openEHR. For this we would need no labels. After that - can we have fewer - we're just confusing people with so many levels.

[wolandscat]

In the short term I agree with Bostjan, let's just get a v0.1.0 (v0.5.0? or whatever) API done. Medium term I think we do need a system (everyone does) or profiling - creating one solves part of our burning need for conformance specifications. I wonder if the following scheme would be clearer:

• R, W, Q - levels for read, write and query 'content' of an identified EHR
• Rp, Wp, Qp - levels for read, write and query 'content' of populations of EHRs. Subsumes R, W, Q.
• Rc, Wc, Qc - levels for read, write and query 'control structures' of an identifier EHR. Subsumes R, W, Q. Or maybe Rv/Wv/Qv - access to 'content version' related-information?

In all of the above, W subsumes R, and Q subsumes R.

Here I assume that 'Q' is support for AQL querying. Not sure if Qc/Qv is needed.

[ErikSundvall]

Of course we can have fewer levels, the suggestion is based on what is useful for operation and what often gets implemented first in new implementations. Actually they were meant to simplify by helping people focus on just implementing neccesities first.

Any concrete change suggestions? [Edit: I wrote this before I saw Tom's comment]

W3 was something I added recently based on SEC+wiki discussions. It could probably just be omitted for now for simplicity, but I think the multi-EHR commit will be needed later by some implementations no matter if it is in specified conformance level or not.

Q1 and Q2 could be merged if you think that is simpler.

[wolandscat]

Actually looking at it, I think W1 is a bit odd, and could only make sense in a certain kind of API. Reason being that all 'writes' to the EHR are always a Contribution. So W1 write is presumably a call that means 'write this one COMPOSITION' to the EHR (as a Contribution, obviously)'. But a call that allows writing N COMPOSITIONs as once is the same really - it still means 'write all this to the EHR as a Contribution'. So I am not sure that W1 and W2 are needed as separate levels. OTOH I suspect you are think about simpler call param structures?

[freshehr]

Attached is what I have been asking people to emulate if they want to get
involved in the NHS Code4Health platform.

I would /query to that set, allow for custom (non-AQL) syntax, but
returning 'standard' Resultset.

Ian
openEHR RESTful.docx

[freshehr]

Template management (upload/download/list of .opt) is, I think important.
There have been concerns that these functions should admin, but they are
important to small-apps developers and for demo/training purposes. This
could of course be configurable i.e hidden for particular situations.

Ian

[ErikSundvall]

@freshehr Ian, I think you responded via mail rather than using the GitHub so the attachments do not show up on the GitHub web.

@wolandscat Tom, regarding W1 it was referring to the simplified "openEHR-for-dummies" discussion/suggestion in the SEC regarding a POST to /compositions or /ehrs/{ehrId}/compositions that somewhat hides the details of the contribution mechanism for beginners and somple use-cases.

W2 was intended for the "proper" contribution-aware multi-object POST to /contributions - the only thing that is needed according to your reasoning above and also what we we used in LiU-EEE. (But in EEE we instead had a reasoning around a "Contribution Builder" to make things easier for develepers.)

[wolandscat]

@ErikSundvall right, now I remember that discussion (takes alzheimers tablets...)

[freshehr]

@ErikSundvall - thanks uploaded document now and tided my enormous sig to keep @wolandscat happy :)

[freshehr]

W1 is very helpful for training purposes, and in fact for the majority of commits in small app systems. W2 is clearly needed but not required in many cases ( though of course there is a contribution being made regardless)

[ErikSundvall]

A thought behind especially R1 and partly W1 was (in addition to be used for minimal demo or first-version systems) to be used also by systems that are not fully openEHR-compliant internally, but that want to (e.g. on-the-fly) convert and expose some legacy data structures (not neccesarily stored in fully openEHR compliant formats or CONTRIBUTIONS). This would be very useful when (slowly) transitioning from legacy to openEHR in e.g. a module-by-module way.

[ErikSundvall]

@freshehr Ian, template handling is something we haven't covered very much in the discussions so far, i satarted a separate issue, #9 for that