Re: Meaningful API's

[Bert Verhees]

On 17-07-18 12:15, Thomas Beale wrote:
One general thing to remember is that there will normally be multiple 
levels of API, from data to domain to business to application. 


Agree, good to list the levels.

Bert


___
openEHR-technical mailing list
openEHR-technical@lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

Re: Meaningful API's

[Bert Verhees]

On 17-07-18 12:05, Ian McNicoll wrote:

This is harder for newbies to understand but


We don't write API's as learning material for newbies, but for 
professional communication, so that is no problem.


Also for the rest I agree.

There is need for API's for interaction between two OpenEhr 
environments, and API's for the rest of communications (that will be 
used most). I mentioned FHIR as example, of course FHIR is not perfect. 
But we cannot deny its success.


A specific message-format-API is not what I am looking for, by combining 
several API's, a developer should be able to craft any message he wants, 
very easy. I have done that a lot, also last year. It is sometimes my 
daily income.


Often we forget that on discussion-lists we are in the year 2525, but on 
the market we still see message types from 20 years ago, HL7v2, EDIFACT, 
XML, vendor specific formats, it all happens a lot. Sometimes the only 
way to communicate with some critical software-products.




___
openEHR-technical mailing list
openEHR-technical@lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

Re: Meaningful API's

[Thomas Beale]

One general thing to remember is that there will normally be multiple 
levels of API, from data to domain to business to application. The APIs 
at those levels are likely to be designed based on different design 
principles, e.g.:


 * data level - API will be typically CRUD and query operations, data
   correspond to the information model of the served resource
 * domain level - API will be typically industry standard concepts,
   e.g. medication list transactions
 * business level - API will be transactional, around processes
   specific to the enterprise, e.g. admission procedures
 * application / presentation - APIs might exist at this level to
   provide user-level interactions (workflow) with data or business
   processes.

An application might be written to talk to one or more such APIs, so its 
view of things will depend on those APIs.


- thomas

On 17/07/2018 09:43, Bert Verhees wrote:

On 16-07-18 16:54, Ian McNicoll wrote:

Hi Bert,

Have a look at what Ripple is doing in terms of 'meaningful APIs'.

See 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/2018-February/014799.html

This is interesting, although, what I understand from it in a "quicky"
This is what I think to have read in that quick information absorption.


___
openEHR-technical mailing list
openEHR-technical@lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

Re: Meaningful API's

[Ian McNicoll]

"The strong point of FHIR (where its success comes from) is that every
application can understand it. For this reason, I think that OpenAPI will
suffice for the purpose."

Which is not actually true, since every FHIR resource needs to be profiled
to be safely understood, often very heavily (see Observations). But I agree
that FHIR does represent (for some use-cases) a more business-oriented API
than openEHR which is deliberatly more low-level, However FHIR, in
practice, is itself much more complex (especially once you add in all the
extensions/ localisations/ terminology bindings and than say a locally
crafted API like Ripple.

The unique point of the openEHR API is that the receiving system (a CDR)
does not have to pull apart the incoming data structures (or at least it
does not require re-engineering for every new structure). This is harder
for newbies to understand but reduces the overall engineering effort
substantially especially for new data structures.

So there is a place for

lower-level API - openEHR service (or whatever, with varying content
representations)

Broad business API -FHIR (for openEHR based on common templates mapped to
local FHIR profiles) - see
https://github.com/Code4Health-Platform/openehr-care-connect-adaptor for an
example. The templates are designed to be UK wide.

Specific business API -  e.g Ripple

depending on your 'consumer'

The native data is complex, you cannot dodge that if you want
to deliver sophisticated health systems.

Ian

Dr Ian McNicoll
mobile +44 (0)775 209 7859
office +44 (0)1536 414994
skype: ianmcnicoll
email: i...@freshehr.com
twitter: @ianmcnicoll


Co-Chair, openEHR Foundation ian.mcnic...@openehr.org
Director, freshEHR Clinical Informatics Ltd.
Director, HANDIHealth CIC
Hon. Senior Research Associate, CHIME, UCL


On Tue, 17 Jul 2018 at 10:01, Bert Verhees  wrote:

> On 16-07-18 16:59, Thomas Beale wrote:
>
> well whether it is 'so good' is in the eye of the beholder, but it is
> 'good enough' for quite a lot of things, things for which we would once
> have expected to be able to use XMI. Anyway, the BMM introduction
> 
> provides some information on why it is there.
>
> BMM does not serve the purpose of describing API's. It serves the
> describing of software models.
>
> API's are communication-protocols. You can compare them with network
> protocols. There can be structures in them, and there are, in JSON, also in
> protobufs.
>
> But these structures do not serve the purpose of building an application
> around it. They only serve to communicate data. The receiving party must be
> able to recognize the structure, but the receiving side does not need to
> know that a list of structures is of a generic type. It will find out when
> reading the message that all the components of a list are from a specific
> type (if it is interested). Maybe for the receiving side, the fact that a
> specific list has generic data-items is not important, because in its own
> universe this is different. The same counts for hierarchy/inheritance. The
> receiving side does not need to know that a structure in message A is
> inherited from a structure in message B.
>
> The receiving side probably will tear apart the structures and reorder the
> data in its own structures.
>
> So any API design method which handles generics and inheritance
> communicates a lot of useless information, unless the other side is exactly
> the same machine, then they have a common center of the universe. However,
> this should never be the purpose of an API, nor the purpose of a message.
>
> The strong point of FHIR (where its success comes from) is that every
> application can understand it. For this reason, I think that OpenAPI will
> suffice for the purpose.
>
> Bert
> ___
> openEHR-technical mailing list
> openEHR-technical@lists.openehr.org
>
> http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org
>
___
openEHR-technical mailing list
openEHR-technical@lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

Re: Meaningful API's

[Bert Verhees]

On 16-07-18 16:59, Thomas Beale wrote:
well whether it is 'so good' is in the eye of the beholder, but it is 
'good enough' for quite a lot of things, things for which we would 
once have expected to be able to use XMI. Anyway, the BMM introduction 
 
provides some information on why it is there.


BMM does not serve the purpose of describing API's. It serves the 
describing of software models.


API's are communication-protocols. You can compare them with network 
protocols. There can be structures in them, and there are, in JSON, also 
in protobufs.


But these structures do not serve the purpose of building an application 
around it. They only serve to communicate data. The receiving party must 
be able to recognize the structure, but the receiving side does not need 
to know that a list of structures is of a generic type. It will find out 
when reading the message that all the components of a list are from a 
specific type (if it is interested). Maybe for the receiving side, the 
fact that a specific list has generic data-items is not important, 
because in its own universe this is different. The same counts for 
hierarchy/inheritance. The receiving side does not need to know that a 
structure in message A is inherited from a structure in message B.


The receiving side probably will tear apart the structures and reorder 
the data in its own structures.


So any API design method which handles generics and inheritance 
communicates a lot of useless information, unless the other side is 
exactly the same machine, then they have a common center of the 
universe. However, this should never be the purpose of an API, nor the 
purpose of a message.


The strong point of FHIR (where its success comes from) is that every 
application can understand it. For this reason, I think that OpenAPI 
will suffice for the purpose.


Bert

___
openEHR-technical mailing list
openEHR-technical@lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

Re: Meaningful API's

[Bert Verhees]

On 16-07-18 16:54, Ian McNicoll wrote:

Hi Bert,

Have a look at what Ripple is doing in terms of 'meaningful APIs'.

See 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/2018-February/014799.html

This is interesting, although, what I understand from it in a "quicky"
This is what I think to have read in that quick information absorption.

In the link is (I think) explained that one should not build a GUI 
around a datamodel, but have their own criteria to build a GUI.
I agree with that, because a GUI serves another purpose then a datamodel 
(in which the data are stored)
The same is also for creating a message, it must not mimic the datamodel 
where it comes from, but have its own criteria, based on 
understandability and structures for others also easy to follow in 
receiving and transmitting.


Unless you are the center of the universe, of course, then you can 
expect others to follow you, that they have the functionality to 
understand and parse what you bring over.


This is interesting because this means that an API does not need to 
export OpenEhr/archetype-structures, they are often not going to be used 
anyway.
So that is not what we want, as a study from Helma van der Linden 
apparently also shows.
A GUI, a message, (an API) should be effective in the context of the 
receiver, not in the context of the sending party.


Thomas called the medication API from the Human API "low level", but 
this was a confusing term. Better would have been to call it primitive, 
or something like that. But what he meant to say was understandable and 
right in that example. But I like to rephrase it because it better fits 
in my thinking. (funny, this communication misunderstanding is a lot 
like API misunderstandings, so context is important.)


Low level in OpenEhr context would mean, exporting the structures as 
they are found inside OpenEhr-storage, Low level would mean in my 
understanding, as close as possible to the source. Mostly, low level is 
more complicated then high level. Compare it with ways of communicating 
computer-instructions: assembly (Low Level, complex, processor-type 
bounded and not fit or interoperability) with Java (High level, not 
complex, runs on every machine).


That is what an API does. It does not want to preserve structures which 
are in use on the sending side, but it wants to exchange data with other 
purposes/platforms in a way that it is easy to understand. We cannot 
expect from the other side that they know how to parse archetypes.


So we could ask ourselves, is "more primitive" worse then "low level"? 
There must be a level between these which is good.
I agree that meta-data, like "created at", "id" should not be mixed up 
with clinical data. So that part is not right in the Human API 
medication call. Maybe there are more points wrong.
But that should not be the discussion. The discussion should be about 
how the API will look like, (and maybe learn from others, because others 
will use the API)


And there is another thing, an API should be stable. Because CKM is 
regarded as a base-structure set for OpenEhr which is sensible to use, 
this does not mean that every OpenEhr installation follows CKM 
completely, partly, or not at all. This is propagated as flexibility. 
CKM is not the center of the universe. An API should therefor not impose 
a structure from CKM on users. It should have its own means of 
communication. This must consist from primitive structures, because many 
software designers which think in other ways must find it usable.


Apart from this interoperability (with other paradigms) thinking, there 
can of course also be a low level API which dumps archetype structures 
over the wall because the other side knows how to parse ADL and knows 
how to store and retrieve archetyped data, so the other side is an 
OpenEhr machine. Between two OpenEhr systems, OpenEhr is the center of 
the universe.


Best regard
Bert Verhees





Ian

Dr Ian McNicoll
mobile +44 (0)775 209 7859
office +44 (0)1536 414994
skype: ianmcnicoll
email: i...@freshehr.com 
twitter: @ianmcnicoll


Co-Chair, openEHR Foundation ian.mcnic...@openehr.org 


Director, freshEHR Clinical Informatics Ltd.
Director, HANDIHealth CIC
Hon. Senior Research Associate, CHIME, UCL


On Mon, 16 Jul 2018 at 15:06, Bert Verhees > wrote:


On 16-07-18 15:56, Bert Verhees wrote:
> But again, the starting point must be the API's defined, maybe in a
> transformerable language like swagger, which seems to connect
well to
> the OpenAPI initiative.(I never liked swagger much, but my last
> experience with it was from years ago, maybe it is better now)
>
> And then you mentioned BMM, I don't know about that. I should
look at
> it, I saw your other email. Do you have somewhere a document why
BMM
> is so good?

The latest version of Open API (swagger became the