API implementation levels about specifications-its-rest HOT 12 OPEN

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.

from specifications-its-rest.

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.

from specifications-its-rest.

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.

from specifications-its-rest.

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?

from specifications-its-rest.

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

from specifications-its-rest.

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

from specifications-its-rest.

@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.)

from specifications-its-rest.

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

from specifications-its-rest.

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

from specifications-its-rest.

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)

from specifications-its-rest.

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.

from specifications-its-rest.

@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

from specifications-its-rest.