REST API specification:OverviewEhrQueryDefinitions

Definitions API

Release
1.0.1
Status
TRIAL
Date
17 Oct 2019
API Endpoint
{baseUrl}/v1/definition
© 2003 - 2019 The openEHR Foundation
The openEHR Foundation is an independent, non-profit community organisation, facilitating the sharing of health records by consumers and clinicians via open standards-based implementations.
Licence image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/
Support Issues: Problem Reports
Web: specifications.openEHR.org

Amendment Record

Issue Details Raiser, Implementer Completed
Release-1.0.1
3.0 SPECITS-32: Fix typos and minor documentary errors (fixes SPECPR-253, SPECPR-289) J Smolka, P Pazos, E Sundvall, T Beale, S Iancu 1 Sep 2019
2.2 SPECITS-24: Added changelog J Smolka, S Iancu 12 May 2019
SPECITS-25, SPECITS-29: Change layout and structure J Smolka, S Iancu 12 May 2019
2.1 Update links to new openEHR specifications website S Iancu 16 Dec 2018
Release-1.0.0

Definitions

This is a collection of resources to manage the clinical definitions and models (e.g. templates, queries) of an openEHR Server.

Actions upon resources of this group are also formally described in the Definition Package of the Abstract Service Model.

ADL 1.4 TEMPLATE

Management of ADL 1.4 Operational Templates (OPTs). These templates can be created using modelling tools such as the Template Designer.

POST {baseUrl}/v1/definition/template/adl1.4
Requestsexample 1
Headers
Content-Type: application/xml
Prefer: return={representation|minimal}
Body
<template xmlns="http://schemas.openehr.org/v1">
    <language>
        <terminology_id>
            <value>ISO_639-1</value>
        </terminology_id>
        <code_string>en</code_string>
    </language>
    <description>
        <original_author id="Original Author">Not Specified</original_author>
        <lifecycle_state>Initial</lifecycle_state>
        <other_details id="MetaDataSet:Sample Set ">Template metadata sample set </other_details>
...
Responses201400409

201 Created is returned when the template has been successfully uploaded. Server assigned template_id SHOULD be returned as Location response header. Depending on the header Prefer either an empty body or a full representation body is returned.

Headers
Content-Type: application/xml
Location: {baseUrl}/definition/template/adl1.4/Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747
Body
<template xmlns="http://schemas.openehr.org/v1">
    <language>
        <terminology_id>
            <value>ISO_639-1</value>
        </terminology_id>
        <code_string>en</code_string>
    </language>
    <description>
        <original_author id="Original Author">Not Specified</original_author>
        <lifecycle_state>Initial</lifecycle_state>
        <other_details id="MetaDataSet:Sample Set ">Template metadata sample set </other_details>
...

400 Bad Request is returned when unable to upload a template, because of invalid content.

409 Conflict is returned when a template with same template_id already exists.

Upload a template
POST/definition/template/adl1.4

Upload a new ADL 1.4 operational template (OPT).

GET {baseUrl}/v1/definition/template/adl1.4
Responses200

200 OK is returned when the template list is successfully retrieved.

Headers
Content-Type: application/json
Body
[
  {
    "template_id": "string",
    "concept": "string",
    "archetype_id": "string",
    "created_timestamp": "2017-08-14T19:24:56.639Z"
  }
]

List templates
GET/definition/template/adl1.4

List available ADL 1.4 operational templates on the system.

GET {baseUrl}/v1/definition/template/adl1.4/Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747
Responses200400404

200 OK is returned when the template is successfully retrieved.

Headers
Content-Type: application/xml
Body
<template xmlns="http://schemas.openehr.org/v1">
    <language>
        <terminology_id>
            <value>ISO_639-1</value>
        </terminology_id>
        <code_string>en</code_string>
    </language>
    <description>
        <original_author id="Original Author">Not Specified</original_author>
        <lifecycle_state>Initial</lifecycle_state>
        <other_details id="MetaDataSet:Sample Set ">Template metadata sample set </other_details>
...

400 Bad Request is returned when the request has invalid template_id (i.e. an incorrectly formatted template_id).

404 Not Found is returned when a template with the specified template_id does not exist.

Get template
GET/definition/template/adl1.4/{template_id}

Retrieves the ADL 1.4 operational template identified by template_id identifier.

URI Parameters
HideShow
template_id
string (required) Example: Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747

template identifier

ADL 2 TEMPLATE

Management of ADL 2 Operational Templates (OPTs).

POST {baseUrl}/v1/definition/template/adl2/?version=1.0.1
Requestsexample 1
Headers
Prefer: return={representation|minimal}
Body
template (adl_version=2.0.5; rm_release=1.0.2)
    openEHR-EHR-COMPOSITION.test.v1.0.0

specialize
    openEHR-EHR-COMPOSITION.discharge.v1

language
    original_language = <[ISO_639-1::en]>

description
    lifecycle_state = <"unmanaged">
    original_author = <
        ["name"] = <"Ian McNicoll">
        ["organisation"] = <"openEHR Foundation">
        ["email"] = <"ian.mcnicoll@openehr.org">
...
Responses201400409

201 Created is returned when the template has been successfully uploaded. Depending on the header Prefer either an empty body or a full representation body is returned.
The version in the Location header is optional.

Headers
Location: {baseUrl}/definition/template/adl2/openEHR-EHR-COMPOSITION.test.v1.0.0/1.0.1

400 Bad Request is returned when unable to upload a template, because of invalid content.

409 Conflict is returned when a template with given template_id and version already exists.

Upload a template
POST/definition/template/adl2/{?version}

Upload a new ADL 2 operational template.

URI Parameters
HideShow
version
string (optional) Example: 1.0.1

a SEMVER version format

GET {baseUrl}/v1/definition/template/adl2
Responses200

200 OK is returned when the template list is successfully retrieved.

Headers
Content-Type: application/json
Body
[
  {
    "template_id": "string",
    "version": "1.7.1",
    "concept": "string",
    "archetype_id": "string",
    "created_timestamp": "2017-08-14T19:24:56.639Z"
  }
]

List templates
GET/definition/template/adl2

List available ADL2 operational templates on the system.

GET {baseUrl}/v1/definition/template/adl2/openEHR-EHR-COMPOSITION.test.v1.0.0/1.0
Responses200400404

200 OK is returned when the template is successfully retrieved.

Body
template (adl_version=2.0.5; rm_release=1.0.2)
    openEHR-EHR-COMPOSITION.test.v1.0.0

specialize
    openEHR-EHR-COMPOSITION.discharge.v1

language
    original_language = <[ISO_639-1::en]>

description
    lifecycle_state = <"unmanaged">
    original_author = <
        ["name"] = <"Ian McNicoll">
        ["organisation"] = <"openEHR Foundation">
        ["email"] = <"ian.mcnicoll@openehr.org">
...

400 Bad Request is returned when the request has invalid template_id (i.e. an incorrectly formatted template_id).

404 Not Found is returned when a template with the specified template_id and version_pattern does not exist.

Get template
GET/definition/template/adl2/{template_id}/{version_pattern}

Retrieves the ADL2 operational template identified by template_id identifier.

If version_pattern is specified then the latest template version with given prefix pattern is returned. If version_pattern is omitted, then the latest version of the operational template is returned.

URI Parameters
HideShow
template_id
string (required) Example: openEHR-EHR-COMPOSITION.test.v1.0.0

template identifier

version_pattern
string (optional) Example: 1.0

SEMVER version pattern; this can be a complete version (i.e. 1.7.1) or partial prefix (i.e. 1.0)

STORED QUERY

Management of stored (registered) queries in the system.

Stored queries must have a name (qualified_query_name) and an optional version number.

Implementers can choose a schema for query names, such as <namespace>::<query-name>, this way queries can be separated by domain, etc. Namespace (if used) should be reverse domain name, which allows for separation of stored queries by teams, companies, etc. Example of a qualified query name: org.openehr::compositions.

In the future several standard openEHR stored queries might be developed, those will use namespace org.openehr.

Version numbers, if used must be in SEMVER style (i.e. major.minor.patch). If only a partial version is supplied or version is not supplied at all, the system must use the latest version with the supplied prefix - i.e. if only major or major.minor is used, then the latest query version with supplied prefix will be used.

Queries can be executed using the query endpoint.

GET {baseUrl}/v1/definition/query/org.openehr::compositions
Responses200

200 OK is returned when the query resources are successfully retrieved.

Headers
Content-Type: application/json
Body
[
  {
    "name": "org.openehr::compositions",
    "type": "aql",
    "version": "1.0.1",
    "saved": "2017-07-16T19:20:30.45+01:00",
    "q": "SELECT c FROM EHR e[ehr_id/value=$ehr_id] CONTAINS COMPOSITION c[$compositionid] WHERE c/name/value = 'Vitals'"
  },
  {
    "name": "org.openehr::compositions",
    "type": "aql",
    "version": "3.1.7",
    "saved": "2018-06-13T09:37:20.53+01:00",
    "q": "SELECT c FROM EHR e[ehr_id/value=$ehr_id] CONTAINS COMPOSITION c[$uid] WHERE c/name/value = 'Vitals'"
  }
]

List stored queries
GET/definition/query/{qualified_query_name}

Parameter qualified_query_name is optional. If omitted they are treated as “wildcards” in the search.

Examples:

  • GET {baseUrl}/definition/query/org.openehr will list all versions of all queries with names starting with org.openehr

  • GET {baseUrl}/definition/query/org.openehr::compositions will list all versions of the query named org.openehr::compositions

URI Parameters
HideShow
qualified_query_name
string (optional) Example: org.openehr::compositions
PUT {baseUrl}/v1/definition/query/org.openehr::compositions/1.0.1?type=AQL
Requestsexample 1
Headers
Content-Type: text/plain
Body
SELECT c 
FROM EHR e[ehr_id/value=$ehr_id] 
CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] 
CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] 
WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp
Responses200400409

200 OK is returned when the query was successfully stored.

Headers
Location: {baseUrl}/definition/query/org.openehr::compositions/1.0.1

400 Bad Request is returned when the server was unable to store the query. Could be due to incorrect request body (could not be parsed, etc), unknown query type, etc.

409 Conflict is returned when a query with the given qualified_query_name and version already exists on the server.

Store a query
PUT/definition/query/{qualified_query_name}/{version}{?type}

Store a new query on the system.

URI Parameters
HideShow
qualified_query_name
string (required) Example: org.openehr::compositions

query name

version
string (optional) Example: 1.0.1

query SEMVER version number

type
string (optional) Example: AQL

indicating the query language/type

GET {baseUrl}/v1/definition/query/org.openehr::compositions/1.0.1
Responses200404

200 OK is returned when the stored AQL is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "name": "org.openehr::compositions",
  "type": "aql",
  "version": "1.0.1",
  "saved": "2017-07-16T19:20:30.45+01:00",
  "q": "SELECT c FROM EHR e[ehr_id/value=$ehr_id] CONTAINS COMPOSITION c[$compositionid] WHERE c/name/value = 'Vitals'"
}

404 Not Found is returned when the stored AQL with supplied qualified_query_name and version does not exist.

Get stored query and info/metadata
GET/definition/query/{qualified_query_name}/{version}

URI Parameters
HideShow
qualified_query_name
string (required) Example: org.openehr::compositions

query name

version
string (optional) Example: 1.0.1

query SEMVER version number

Generated with aglio on 17 Oct 2019