I live sometime in the OpenEhr world, so I am not surprised that it is a rather low level API. In fact it is a bit hard to recognize quick what it is about. And it fits perfectly to the philosophy of OpenEhr. The API is not semantically rich. It are the archetypes which are semantically rich, the API IS GENERIC. So it is fine. I am not criticizing.
I found another API on the Internet, in fact, I found many. They are all semantically rich. They all have functions like “Which medication does the patient take”.
In OpenEhr there is only a function to execute a query to find semantically meaningful data. The API itself offers no further clues.
Again, this is not criticizing, it fits in the philosophy of OpenEhr. It is impossible to write queries for the customers, because we do not know the archetypes they use. The customer is helpless without the expertise of OpenEhr specialists, of which are not many people on the world. I think, from marketing point of view this is hard to sell, because other vendors offer semantically rich API’s out of the box. Only a web developer, without special education is then needed to write a GUI.
I think it is not necessary that it is that way. The premise that we don’t know which archetypes customers use is not always true. In fact, from many customers it is known that they use archetypes from CKM. So, my point:
How nice would it be when CKM would publicly be extended with queries which fit on the archetypes, which can be used to create a semantically rich API.
This would have to advantages.
It would be a strong marketing point. An OpenEhr customer would not anymore need expensive expertise to do simple things like querying which medication a patient uses.
It would motivate customers to use CKM archetypes (Which maybe do not use them now, or edit them without telling anyone, and maybe even without changing the identifier) because this would then have an extra advantage to stay closely connected to CKM.
the addition of business-level transactional APIs, e.g for medication list, e-pharmacy, or other business level functions is certainly intended and envisaged. It’s just not the first step.
Such APIs would convert relatively simple transactional concepts e.g. get_medication_list(), suspend_medication() etc to what may be non-trivial information structures defined by specific archetypes, which would be valuable for the reasons you say. Also: they improve data interoperability because complex structures (say, Care Plans) are guaranteed to always be the correct structure due to the API, whereas manual creation might end up with different variations.
I agree, thanks for your reply. What I would find interesting is that there would be an API-set, which is defined from good reasoning, how a specific API should look like. I found an example on the Internet from a Californian startup, which may be far from complete and maybe there is otherways much to improve, but they incorporate also Wellness and we don't see that a lot. But the final judgment I let that to people who studied for it.
That is part one, an API, defined without the material of what already is available in OpenEhr, in CKM, the Reference Model, AQL.
And then Part Two, how can CKM and the Reference Model serve to create this API, and that would result in implementation in AQL, and maybe, if necessary, but hopefully not, functions to fill up the gaps which cannot be filled up by the traditional OpenEhr methods.
Only in this way we can find shortcomings, or have a party because there are no shortcomings and we are able to create a API precisely as we would find perfect at the moment of creating, by just using CKM and the Reference Model and AQL. That would be a real convincing victory.
But maybe it is too hot and dry this weeks, and I get dreamy at the end of the day.
I totally agree with your view that CKM would carry AQL queries that could be reviewed and potentially published in the same way that the archetypes and templates are. I think it would have enormous impact on healthIT and unleashing the power of openEHR and atomic data.
It was a high priority in my strategic plan for CKM but I wasn’t able to get inhouse resources when CKM was my responsibility. Now it is in the hands of whoever is the new product manager for CKM and the new funders of Ocean to assign the resources, although judging by their previous business priorities I am concerned that CKM may not be a high priority item.
I would say the current API is a platform API, not an end-user app API. I would expect more domain semantic richness on an end-user app API.
I think in the future we’ll need both, but the end-use app API would be more implementation dependent, but we can reach some kind of agreement to have some basic set of common services.
First for Heather: Thanks for being open on your concerns.I think that the reply from Pablo is also important. He pledges (like you but more explitly) for common ground on API’s, of course also for application specific API’s.
But that common ground needs to be defined first as a starting point. Inspiration could be found in the link I send as a reply to Thomas, yesterday.
And for that common ground writing AQL would not be that hard, and it would be necessary.
But I also tast in the reply of Pablo something like wanting to wait until there is an agreement. I don’t think that will work. Waiting for agreements can take forever. It is a plan without time frame.
Better is to look for agreements (agreed API) with suitable partners, and when they are found, some pressure will grow on the market, and that can make commercial motivated funders see the importance of that agreement of which CKM is from the OpenEhr side indispensable.
There is, however, one important step. The agreement can only be platform independent, not only at the front side, but also on the backend side.
Here we do it with OpenEhr, others will do it with FHIR messaging, and others will create layers between vendor API’s and the agreed API.
The profit will be in the marketpressure caused by that common API, and the platform-differences will be in what is outside the agreement.
I just had a look at this. It’s pretty low-level. See for example. It seems to be a competitor to FHIR in some way, since it is not using FHIR. Anyway, there are two kinds of things we can do, both more advanced than this. The first is to generate APIs from templates, in the same way we generate a TDS (Template Data Schema, which is an XSD) from a template. All we need to do to build a transformer, not hand-build APIs (that’s last century thinking). This means we would have a way to generate an API from any template, i.e. any content. This kind of API is one way to get data out of a system. The second interesting thing to do is to design transactional API models for things like ‘Medication List’ and ‘Care Plan’, which have a functional interface. In the first instance we could do this in UML (same approach as the current ) or IDL, and build a generator to output REST APIs. This style of API is functional and transactionally oriented, and is the basis of writing changes into the system. If there are people interested in working on either of these, we can put together a working group (or two). - thomas
Aren’t we all? Depends on what you call low level. In this discussion, yesterday, I called the OpenEhr API low-level, because it had no meaningful API’s at all. So calling this also low-level might be confusing. REST is bounded to http 1.1 which is from 1997, it is spoiling of resources, it needs to translate everything to strings which cost performance in processing time, and performance in bandwith. But we can do it with that for coming two years. I think by then the world (also browsers for web-application front ends, also in mobile platforms) are running http 2.0, which is stable since 2015.
It was not particularly meant as a criticism, but have a look at this: We can see that: Maybe this is fine for some uses, maybe many. But if you look at the CKM or Apperta or other medication archetypes, it’s easy to see that obtaining that kind of data would be somewhat painful with this interface. An interface of similar simplicity, but from templates using those archetypes however would be interesting… well some templates are being slowly added to the international CKM and other CKMs, but generally, templates are what local users and vendors create themselves. Since they don’t break archetypes, it is safe to create them according to your own data-set needs. indeed. Feel free to replace where I wrote ‘REST’ with GraphQL, protobuf3, Apache Thrift etc agree. - thomas
When I said, that API is an example I meant the data they were able to transmit, not the structure. It is not surprising that they use typescript-like data, it is a REST based API, and typescript is the better kind of Javascript, it also fits good on JSON. When looking at the data they represent, I thought, it would be a good example of what a basic API should be able to. So just an example. I explained that in the first email of this thread with this subject. That is true, but isn’t the same true for AQL? AQL is able to do things which templates are not so well designed for, like scanning over datasets of more patients in a single query. Maybe both, templates and AQL are necessary/usable. 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? Bert
Yes, we need to treat AQL queries and query sets more like model artefacts, no doubt about that. 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 provides some information on why it is there. - thomas
XMI is not designed to describe functions, but it is an object-description language, and very limited indeed. And still used and illegally extended, and therefor not fit for exchange of models.
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
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.
“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)
Depends on what you call low level. In this discussion, yesterday, I called the OpenEhr API low-level, because it had no meaningful API’s at all. So calling this also low-level might be confusing. REST is bounded to http 1.1 which is from 1997, it is spoiling of resources, it needs to translate everything to strings which cost performance in processing time, and performance in bandwith. But we can do it with that for coming two years. I think by then the world (also browsers for web-application front ends, also in mobile platforms) are running http 2.0, which is stable since 2015.