Overview

In order to specify concrete service interfaces (i.e. APIs) to openEHR platform product components, a formal, abstract definition of the platform interfaces is useful, so as to be able to state the formal interface call semantics independent of any particular implementation technology. This approach clarifies the distinction between required semantics and the details contingent in any concrete technology, such as SOAP/WSDL, REST, and so on, each of which has its own characteristics and rules.

It is assumed that native APIs are network-accessible via one or more communications protocols, each with an appropriate protocol adapter. Such protocols include the text-based, such as SOAP/WSDL and REST, as well as the many binary protocols, including Google Protocol Buffers, Apache Thrift, Kafka, ZeroC ICE, and Advanced Message Queueing Protocol (AMPQ). The focus of this specification is the nominal 'native API' that is reached by any of these methods, as shown below.

The following figure illustrates the components of the abstract openEHR Platform, along with their interfaces.

Each component has one or more associated interfaces, i.e. abstract service definitions which define a transactional interface to the service represented by the component. Each interface consists of a number of calls, and each call is defined in an abstract way, i.e. independent of the representations and expressions required by a concrete protocol.

This view does not attempt to define a real product architecture as would be developed by an openEHR platform implementor, but it does establish a formal equivalent of any such architecture. Practically, this entails standardised naming of components and the semantics of their logical interfaces so that platform procurers and users can unambiguously refer to the 'Admin service' or the 'EHR service' within technical or commercial documents. The abstract service architecture described here provides platform implementers a standard reference definition for mapping agreed functionality (such as requested in a tender or other solicitation) into their own architectures, which may be organised quite differently.

The services are as follows.

Regardless of the internal organisation of real product architectures, agreement across a community of producers and users of products that claim to conform to a published platform specification, must by definition be based on something formally statable and testable. As noted above, this is described here in the form of logical components which have logical interfaces, each consisting of a set of calls, of which the latter constitute the finest level of specification.

A logical interface call is understood here in the standard computer science manner, i.e. as a callable routine with a formal, typed signature. Good practice usually dictates that such routines should take the form of either pure functions, or pure procedures, but not both: side-effect producing functions should generally be avoided. In other words, interface calls are either queries that return something but do not change state, or commands that cause a change, but don’t compute or return anything. The separation is sometimes known as command / query separation.

The signatures of query and procedure calls thus take the following syntactic forms:

One of the key assumptions of this specification (and indeed formal standardisation in general) is that although real implementations of a platform may have differently structured components and different naming of functions, arguments etc, that there is a formal equivalence between calls specified in a published standard and those in the implementation. Thus, it must be the case that even if three calls in an implementation are required to achieve the effect of a single call in this specification, that the conditions described here prior and after the call(s) are the same in both cases, and also that the three calls taken together are transactionally protected. If this is not true, it implies that the implementation is introducing unspecified semantics.

A fuller specification of any function or procedure includes its semantics, stated in terms of pre-conditions, post-conditions and exceptions, along with documentation of the same. This is exactly as found in any standard library in most programming languages, and indeed, standardised meta-data keywords and labelling have evolved in most programming documentation systems to support exactly this kind of specification, even where the language doesn’t directly support some of its features, such as pre- or post-conditions.

This specification uses the same form of specification, which can be illustrated as follows:

The above kind of specification can in general be easily mapped to any concrete API technology. In each case, how the arguments are expressed, details of serialisation (for text-based technologies like SOAP and REST), error handling, etc, will be different. Google protocol buffers for example uses an OMG IDL-like approach to specification, i.e. structured type definitions. REST on the other hand is a web-based type of API normally mapped onto HTTP verbs, URIs and HTTP error codes.

The intent of the current specification is thus to express the abstract element of each interface call, so that both back-end semantics can be correctly designed, and API definitions can be correctly written and tested.

The openEHR Platform Service Model package structure is illustrated below. It consists of the packages common, definition and interface. The second contains the service components, while the third contains the interfaces attached to each service component.