The REST API Team (Bostjan Lah, Erik Sundvall, Sebastian Iancu, Heath Frankel, Pablo Pazos, and others on the openEHR SEC and elsewhere) have made a 0.9.0 Release of the openEHR ITS (Implementation Technology Specifications) component, in order to make a pre-1.0.0 release of the REST APIs available for wider comment.
LINKS: The generated Apiary documentation can be found here, while the .apib files are here in Github (see mainly the includes directory).
This release is intended to be a ‘core basics’ foundation of APIs to build on, and some services like CDS, and more sophisticated querying (e.g. that Erik Sundvall has published in the past) will be added subsequently.
We are aiming to release 1.0.0 at the end of February 2018, at which point the formal process kicks in.
Since we are in Release 0.9.0, the formal PR/CR process is not needed, and you can comment on the openEHR technical mailing list or if you want to raise a Problem Report (PR) you can do so on the PR Jira tracker. If you do this, please set the Component and Affects Version fields appropriately:
Apart from its primary use in programming openEHR applications, the REST API will be the first technical interface via which conformance will be determined for openEHR system components, as shown in this late draft conformance specification.
This work, along with implementation of the Task Planning (clinical workflow) specification promises to make 2018 an interesting year.
There are some problems with defining API’s in technical detail. They will never last long, and if they are inseparable from the standard, then it will hurt the standard. That is also the problem with REST and FHIR.
For example, the is a lot of criticism on REST, it is an HTTP-based-standard with a very limited vocabulary, I believe, four words, PUT, GET, POST and DELETE. REST is meant for CRUD based operations only. And GET does not allow a body, only a request. That is also a problem, because else one would be able to forget al the simplified CRUD stuff and use GET for everything as a kind of protocol-layer.
This four words vocabulary makes people to get in all kind of twists to find one of the four possibilities to get their call to fit in and still not looking silly. From semantic point of view a very undesirable situation. I have once written an OpenEHR kernel, about twelve years ago, in SOAP, which has other negative implications, but at least, it was not confusing from semantic point of view. But the story was, the developers around that kernel wanted a REST based platform, so they wrote middleware around my kernel in which they implemented a REST layer. in 2009 that was a common way to do this kind of things. I made the middleware-layer superfluous by writing a REST-based API.
If I would write a kernel again, I would make it a series of microservices communicating with each other over high performance gRPC. Normal functions, not semantically limited by REST limitations.
Now already, browsers will work with HTTP/2, this will be the end days of REST also, because REST is very HTTP/1.1 protocol. That will also be a problem for FHIR, because, translating the four REST words to normal function-calls (f.e. gRPC, which will be implemented in all programming languages/browsers) will look silly.
Browser frameworks like Angular (developed by Google) will support gRPC on HTTP/2. Already, all current browsers support HTTP/2. On this page you see a Javascript implementation of gRPC:
https://grpc.io/docs/quickstart/node.html
Will REST still work on HTTP/2? Of course it will, you can also ride with an oldtimer on a modern highway. But it will not be as comfortable and fast as possible.
Will gRPC not have the same problem as REST now has (becoming outdated)? Yes it will, but gRPC does not have a CRUD-limited vocabulary, so it will be no problem rewrite the function-calls in a follow up.
Best regards
Bert Verhees
Hi Bert,
there are various possible responses here. One of your criticisms is that overlaying a comms protocol on the HTTP protocol is potentially problematic, and secondly that there are different flavours of HTTP; and further that the REST way of defining APIs is just one technical approach. These are correct observations in my view.
We understand that there will be, in the future:
a) other flavours of REST (see https://martinfowler.com/articles/richardsonMaturityModel.html for example)
b) non-REST protocols – SOAP will probably exist for some time
c) binary protocols like google protobuf3, various flavours of object RPC and so on.
In order to define API semantics in an abstract way, i.e. independently of the REST or other concrete technology, we have a draft abstract specification – https://www.openehr.org/releases/SM/latest/openehr_platform.html
Definitions of the same APIs in other technologies like gRPC are expected and encouraged, and I see the abstract definition as the best source for writing a new technology API, such as gRPC.
We will need input from the community to know how to adjust the overall specification approach into the future, so that we end up with a good technology-independent API definition (PIM, in OMG terms) and an efficient way of writing any new concrete expression (PSMs).
So, for now, REST is just the first one out of the gate, and it’s a high priority, to enable application programmers to work quickly.
I understand, that mitigates, for me, the whole issue. 😉