API Overview

Authentication and authorization ¶

Services SHOULD implement and support an HTTP Authentication and Authorization framework (which can support various schemes) but there is no assumption or recommendation being made in this specification about which authentication scheme should be used by services and clients. See RFC 7235 or Mozilla’s HTTP Authentication for details on this subject.

If an Authentication and Authorisation framework is present, services MUST properly use WWW-Authenticate and/or Proxy-Authenticate response headers and return HTTP status code 403 Forbidden or 401 Unauthorized or 407 Proxy Authentication whenever applicable, and clients MUST properly use Authorization and Proxy-Authorization in their request headers.

Options and conformance ¶

HTTP headers ¶

Standard HTTP Request and Response headers are described by RFC 7231 and by the IANA Message Headers. The following describes the use of a subset of these headers, as well as the custom headers used by an openEHR API.

The openEHR-VERSION and openEHR-AUDIT_DETAILS headers

When it comes to committing content to an openEHR system, for all change-controlled resources (e.g. COMPOSITION, EHR_STATUS, FOLDER, etc.) the services are performing versioning under the hood. The ‘native’ way of committing is to use a CONTRIBUTION and wrap the content as a VERSION. To keep things simpler and consistent, services MUST also allow PUT, POST and DELETE methods directly on these change-controlled resources. However, these operations MUST internally be executed using the ‘native’ way.

In order to allow clients to provide committal metadata, services MUST accept openEHR-VERSION and openEHR-AUDIT_DETAILS custom request headers. For clients, it is RECOMMENDED to provision these headers based on authentication and authorization runtime data. Below is a complex example of these request headers used in a PUT action to update a COMPOSITION:

openEHR-VERSION.lifecycle_state: code_string="532"
openEHR-AUDIT_DETAILS.change_type: code_string="251"
openEHR-AUDIT_DETAILS.description: value="An updated composition contribution description"
openEHR-AUDIT_DETAILS.committer: name="John Doe", external_ref.id="BC8132EA-8F4A-11E7-BB31-BE2E44B06B34", external_ref.namespace="demographic", external_ref.type="PERSON"

None of these headers are mandatory, but whatever is provided it MUST be merged with the default VERSION and VERSION.audit_details attributes on commit runtime.

Below a list of code_string values and their meaning (taken from openEHR terminology):

The If-Match header and accidental overwrites

The use case of this is described by RFC 7232.

If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"

This HTTP request header SHOULD be used by the clients to prevent accidental overwrites when multiple user agents might be acting in parallel on the same resource. This is only required by a small set of resources of this specification, as in most of the other cases the preceding_version_uid path segment is instead required in order to prevent such accidental overwrites. In case a service receives this header, and the condition evaluates to false, it MUST respond with HTTP status code 412 Precondition Failed and return also latest version_uid in the Location and ETag response headers.

The openEHR-TEMPLATE_ID header

This request header MUST be used whenever committing COMPOSITION (via PUT or POST methods) using a simplified data format which does not support TEMPLATE_ID value under an equivalent LOCATABLE.archetype_details.template_id attribute of contained data.

The Location and openEHR-uri header

This response header indicates the resource location (URL). According to RFC 7231, it is used to refer to a specific resource in relation to the response. The type of relationship is defined by the combination of request method and status code semantics. The identifiers part of this URI-reference SHOULD comply with resource identification semantics of this specification.

Services MUST return this header whenever a create or update operation was performed, but it MAY return this header on other operation or action. Example:

Location: {baseUrl}/ehr/347a5490-55ee-4da9-b91a-9bba710f730e/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2

See representation details negotiation section for more details on how use this header.

If services have support to generate resource URL as specified by the DV_URI/DV_EHR_URI format, then they MAY send also openEHR-uri response header. Example:

openEHR-uri: ehr:/347a5490-55ee-4da9-b91a-9bba710f730e/compositions/87284370-2D4B-4e3d-A3F3-F303D2F4F34B

The Prefer header

This request header MAY be used by clients for resource representation negotiation. See more details on representation details negotiation section.

The ETag and Last-Modified headers

These headers are mainly related to whether or not a returned resource may be cacheable. Their purpose is to give clients information about the state of the requested resources.

According to RFC 7232,

The “ETag” header field in a response provides the current entity-tag for the selected representation, as determined at the conclusion of handling the request. An entity-tag is an opaque validator for differentiating between multiple representations of the same resource, regardless of whether those multiple representations are due to resource state changes over time, content negotiation resulting in multiple representations being valid at the same time, or both.

The ETag response HTTP header contains a string token that the server associates with a resource in order to uniquely identify the state of that resource over its lifetime. The value of the token changes as soon as the resource changes. An example of such header value format is:

ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"

Servers MAY choose their own format for this header, but the recommended value is the unique identifier of the requested resource (e.g. VERSIONED_OBJECT.uid.value, VERSION.uid.value, EHR.ehr_id.value, etc).

The Last-Modified response HTTP header contains the datetime of the last modification of targeted resource which should be taken from VERSION.commit_audit.time_committed.value. An example of such header value format is:

Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT

These two headers SHOULD be present in all responses targeting VERSION, VERSIONED_OBJECT or other resources that have similar unique identifier.

HTTP status codes ¶

To indicate the status of the request, or the executed operation, one of the HTTP status codes MUST be used, as described above. Meaning of these codes may be further detailed (nuanced) in this specification by particular responses. If required, other status codes MAY be used by implementations as long as their usecase is not conflicting or overlapping with above codes.

Status code 400 indicates a bad request or generic client-side error, used when no other 4xx error code is appropriate. The client SHOULD NOT repeat the request without modifications.

In case of errors (HTTP status codes 400-500), the services MAY return more details (if Prefer: return=representation request header is present). Example:

some codes/messages https://github.com/ppazos/cabolabs-ehrserver/wiki/API-error-codes-and-messages and http://veratechnas1.synology.me:13606/InstanceValidator/rules.html

{
    "message": "Error message",
    "code": 90000,
    "errors": [
        {
            "_type": "DV_CODED_TEXT",
            "value": "Error message",
            "defining_code": {
                "terminology_id": {
                    "value": "local"
                },
                "code_string": "9000"
            }
        },
        {
            "_type": "DV_CODED_TEXT",
            "value": "Secondary error message",
            "defining_code": {
                "terminology_id": {
                    "value": "local"
                },
                "code_string": "8000"
            }
        }
    ]
}

Resources ¶

For the openEHR API, a Resource is an instance object of a specific openEHR class (type) that can be identified, addressed, handled or managed by the service. The following are examples of openEHR resources and their types:

• top-level content structure types, such as COMPOSITION, EHR_STATUS, FOLDER, PARTY, etc.

• version containers, such as VERSIONED_COMPOSITION, VERSIONED_EHR_STATUS, etc. or their containing VERSION

• other non-versioned resources, such as EHR, CONTRIBUTION, RESULT_SET, etc.

• definitions, such as TEMPLATE, ARCHETYPE, QUERY

Types defined by openEHR specification are always capitalized when used in this specification. For a list of all available types or a particular type definition please refer to the class index.

Resource identification ¶

An important aspect of a RESTful service is to be able to address resources via URIs/URLs using HTTP verbs (methods). Each resource has an identifier which is unique within the system for that resource type, usually consisting of at least a globally unique identifier (UUIDs). Once the resource is persisted by the service, the identifier is assigned and will never change for that resource instance.

Depending on the resource type and on the use cases, there are several identifier types (and formats):

• a versioned_object_uid for identifying a VERSIONED_OBJECT (i.e. a version container),

• a version_uid for identifying a VERSION from the version container,

• an ehr_id to identify an EHR,

• a template_id or a qualified_query_name used to identify various definitions.

The version_uid is the unique identifier of a VERSION, in the lexical form of object_id :: creating_system_id :: version_tree_id, where the object_id has the same value as the containing VERSIONED_OBJECT identifier taken from VERSIONED_OBJECT.uid.value.

As examples of identifiers, the following request:

GET https://api.openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

is using an URI that contains an EHR identifier 7d44b88c-4199-4bad-97dc-d78268e01398, taken from EHR.ehr_id.value, and a COMPOSITION identifier 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1, taken from COMPOSITION.uid.value, serviced by an openEHR API (of version v1), located at https://api.openEHRSys.example.com.

There are circumstances when resources can be uniquely identified by two different identifiers. For example, assuming that a VERSIONED_COMPOSITION container has the versioned_object_uid identifier 8849182c-82ad-4088-a07f-48ead4180515, and the latest version is 5 (taken from version_tree_id), then that COMPOSITION can be identified either by following explicit URI:

{baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com:5

using the version_uid identifier, as well as by the following implicit URI:

{baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515

However, the latter will only reference the same resource as the former as long as there are no more changes or modifications on that specific version container (i.e. the latest version remains 5).

• NOTE: Since RM Release 1.0.4 it is strongly recommended that the inherited attribute uid be populated in COMPOSITIONs, using the UID copied from the object_id() of the uid field of the enclosing VERSION object. For example, the ORIGINAL_VERSION.uid 87284370-2D4B-4e3d-A3F3-F303D2F4F34B::uk.nhs.ehr1::2 would be copied to the uid field of the COMPOSITION. See Levels of identification chapter of Architecture Overview for more details.

Data representation ¶

Services MUST support at least one of the openEHR XML or JSON formats for resource representation. Alternative formats MAY be also supported, such as a Simplified Data Template (SDT) format. These formats and their associated negotiation protocol is described below.

XML Format ¶

When resources representation is serialized as XML, the request payload as well as the result MUST be valid against published XSDs.

A client MAY use the header Content-Type: application/xml in the requests to specify the XML payload format. If the service cannot process the request payload as XML format is not supported, it MUST respond with HTTP status code415 Unsupported Media Type.

The client SHOULD use the Accept: application/xml request header in order to specify the expected XML response format. If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code 406 Not Acceptable. Proper header Content-Type: application/xml MUST be present in the response of the service unless the response has no content body (HTTP status code 204).

JSON Format ¶

When resources representation is serialized as JSON, the request payload as well as the result SHOULD be valid against published JSON-Schemas.

Note: The JSON-Schema project is under development.

Attribute names must be lowercase snake_case names as specified in the equivalent RM type. For example:

{
    "category": {
        "value": "event",
        "defining_code": {
            "terminology_id": {
                "value": "openehr"
            },
            "code_string": "433"
        }
    }
}

Metadata attributes (those that are not also RM attributes) will always be prefixed by a '_'.

One example is the _type attribute, which should be used to specify the RM type whenever polymorphism is involved, or when the underlying definition in RM type is abstract (dynamic type is different from the static type). This follows same rule as for XML typing. The value of this attribute MUST be the uppercase class name from the RM specification. For example:

{
    "_type": "DV_TEXT",
    "value": "Hello world!"
}

The RM attributes (even required ones) that are Null, empty list or empty arrays SHOULD be absent when serialized as JSON.

The order of attributes in the resource MAY follow the order of attributes in the RM specification of the type of the resource, but this is not mandatory.

A client MAY use the header Content-Type: application/json in the requests to specify the JSON payload format. If the service cannot process the request payload as JSON format is not supported, it MUST respond with HTTP status code 415 Unsupported Media Type.

The client SHOULD use the Accept: application/json request header in order to specify the expected JSON response format. If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code 406 Not Acceptable. Proper header Content-Type: application/json MUST be present in the response of the service unless the response has no content body (HTTP status code 204).

Alternative data formats ¶

Creating data instances according to canonical XML or JSON format is not always straightforward, particularly for developers with minimal exposure to openEHR, and various alternatives have been used in the past to simplify the job of content creation and committal for application developers.

There is an initiative exploring and documenting these alternative formats, which specifications can be consulted at Simplified Data Template (SDT) page.

Note: The specification of Simplified Data Template is under development.

In order to use these formats, content negotiation SHOULD be done in the same manner as for the canonical XML or JSON format above, but instead of application/xml or application/json, clients and servers MUST use:

• application/openehr.wt.flat+json for the simplified IM Simplified Data Template (simSDT) as JSON, based on the ‘FLAT’ version of the ‘web template’ format, originally created by Marand for the Better platform. More information can be found also in their ‘examples’ page, as well as in their open-source implementation and conformance tests.

  EHRbase also has support for this format, and provides information in their documentation.

• application/openehr.wt.structured+json for the structured IM Simplified Data Template (structSDT) as JSON, based on the ‘STRUCTURED’ version of the ‘web template’ format originally created by Marand for the Better platform (see also their ‘examples’).

• text/plain for all textual ADL2 templates or AQL queries,

• application/openehr.nc.flat+json for near-canonical RM Simplified Data Template (ncSDT) as JSON, based on the ECISFLAT format, originally devised for the EtherCIS project,

• application/openehr.tds2+xml for TDS simplification of RM as XML, based on the ‘TDS/TDD’ format originally created by Ocean Health Systems (see this wiki page and the TDD2canonical project).

Note: Other alternative formats may be added in the future, depending on innovative impact, simplicity, popular demand or adoption rate. Current alternative formats might not be supported once they become obsolete or superseded by newer formats.

A client MAY use the header Content-Type in the requests to specify the simplified payload format. If the service cannot process the request payload as the simplified format is not supported, it MUST respond with HTTP status code415 Unsupported Media Type.

The client SHOULD use the Accept request header in order to specify the expected simplified response format. If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code 406 Not Acceptable. Proper header Content-Type MUST be present in the response of the service unless the response has no content body (HTTP status code 204).

Datetime format ¶

The format of the date, time and datetime types should comply with the ISO 8601 Date and Time format specification. The ISO 8601 semantics assumed by openEHR is defined in the classes of the base.foundation_types.time package. It is strongly recommended using the extended format for dates, times and datetimes. This greatly aids human readability, and reduces the need for special date/time parsing and formatting.

HTTP query parameters and path segments that are dates, datetimes, or times, MUST always use the extended ISO 8601 format. The general form of a datetime is YYYY-MM-DDThh:mm:ss.sss[Z|±hh:mm], e.g. 2016-06-23T13:42:16.117+02:00.
Timezone SHOULD be only supplied when needed, otherwise the local timezone is assumed.

Any date, datetime or time value provided as part of the HTTP message body, when creating or updating a resource (e.g. a DV_DATE_TIME value inside the COMPOSITION content), will be preserved as it was sent by the client, and passed to the underlying backend engine as is. Retrieval or querying those resources SHOULD return date, datetime, or time values in the (original) format provided by underlying backend engine, avoiding any format change.

Representation details negotiation ¶

When using the HTTP methods to create or update a resource, the service SHOULD give clients the option of returning either a complete representation of the (modified) resource, or a minimal or no content in the payload response (assuming the operation was successfully completed). See RFC 7240 for more details on how achieve this using Prefer header. The client MAY choose any of the following:

• send Prefer: return=minimal to inform the service that prefers only a minimal response to a successful request. A Location header indicating the direct URL to access the resource MUST be part of the service response. If there is no payload content to be returned, the service SHOULD use HTTP status code 204 No Content.

• send Prefer: return=representation to inform the service that prefers a full representation response to a successful request. A Location header indicating the direct URL to access the resource MAY be part of the service response, and the payload content SHOULD include a full representation.

In case no Prefer header is present in request, the default response policy is return=minimal.

Another preference is related to following and resolving OBJ_REF identifiers. Under some circumstances a client MAY indicate that prefers response containing full or partial resource representation instead of references to resources using OBJ_REF. A typical case is a list of COMPOSITIONs part of an EHR, which, strictly following RM specification, should always return list of OBJ_REF, but sometimes clients prefers to get COMPOSITIONs. Services that have this capability implemented SHOULD accept and honor Prefer: resolve_refs request header.

Prefer: return=representation, resolve_refs