Back to top

OpenEHR EHR REST API (v0.1 proposal)

The following is a proposal for an OpenEHR EHR REST API. It is not complete and might still change completely before the final release.

The following specifications are not intended to describe an existing API but rather an abstract blueprint to which each openEHR implementation should adhere to.

The openEHR EHR REST API enables interaction with an openEHR service in a RESTful manner.

Considerations

About versionSelector

In many places parameter versionSelector is used to select a specific version (or associated data object) of a VERSIONED_OBJECT and can have the following values:

  • fixed string: LATEST_TRUNK_VERSION

  • a specific timestamp in the ISO8601 format (e.g. 2015-01-20T19:30:22.765+01:00)

  • a versionUid (VERSION unique identifier)

  • a uid (VERSIONED_OBJECT unique identifier)

When the versionSelector parameter is not provided, the latest trunk version is returned, which is the same as specifying versionSelector=LATEST_TRUNK_VERSION.

Glossary

Throughout these specifications a set of short terms is being used as described below:

Term Description
ehrId The string value for an EHR identifier, stored under EHR.ehr_id.value, usually an UUID or GUID
uid The string value of a VERSIONED_OBJECT unique identifier, stored under VERSIONED_OBJECT.uid.value, e.g. 8849182c-82ad-4088-a07f-48ead4180515
versionUid The string value of a VERSION unique identifier, stored under VERSION.uid.value, e.g. 8849182c-82ad-4088-a07f-48ead4180515::example.domain.com::1
versionSelector The string value of a VERSION unique identifier, a specific timestamp or the string LATEST_TRUNK_VERSION

Data representation

JSON Format

  • attribute names will be lowercase snake-case names as specified in the RM spec. For example:

    • context : {“start_time”: “2016-01-01T00:00Z”}
  • metadata attributes (those that are not also RM attributes) will always be prefixed by a ‘@’

  • we will use a @type attribute to specify RM type which will be upper-case class name from the RM spec: { “@type”: “DV_TEXT”, “value”: “Hello world!” }

  • null RM attributes will be absent when serialized as JSON

Datetime format

It is recommended to always use canonical ISO8601 expanded format, e.g. 2016-06-23T13:42:16.117+02:00, but any other valid ISO8601 datetime is accepted.

Any datetime value provided by a create or update action will be preserved as it was sent (i.e. if composition was saved as narrow format, it will always return the way it was).

EHR

EHR

Management of EHR resources.

Create a new EHR
POST/ehr

Create a new EHR with an auto-generated identifier. Request body may contain ehr_status and ehr_access attributes. When provided these resources will also be created as part of the create EHR action, otherwise default resources will be created automatically by the service.

Example URI

POST http://www.openehr.org/api/ehr
Request
HideShow
Headers
Prefer: return={representation|minimal}
Body
{
    "commit_audit": {
        "description": "Commit audit description",
        "committer": {"@type": "PARTY_IDENTIFIED", ... }
    },
    "ehr_status": { ... },
    "ehr_access": { ... }
}
Response  201
HideShow

201 Created is returned when a new EHR has been successfully created. The EHR resource is returned in the body when the Prefer header has the value of return=representation.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}
Body
{
    "system_id": {...},
    "ehr_id": {...},
    "ehr_status": "versioned ehr status uid",
    "ehr_acess": "versioned ehr access uid",
    "directory": {},
    "time_created", "..."
}
Response  400
HideShow

‘400 Bad Request’ is returned when unable to create a new EHR due to bad client Request, e.g. malformed syntax.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised to be performed.

Create a new EHR with ehrId
PUT/ehr/{ehrId}

Create new EHR with the specified EHR identifier. The request body may contain ehr_status and ehr_access attributes, which will be used to create these initial resources associated with the new EHR. When the ehr_status or ehr_access attributes are not provided, defaults resources will be created by the service.

Example URI

PUT http://www.openehr.org/api/ehr/ehrId
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

Request
HideShow
Headers
Prefer: return={representation|minimal}
Body
{
    "commit_audit": {
        "description": "Commit audit description",
        "committer": {"@type": "PARTY_IDENTIFIED", ... }
    },
    "ehr_status": {...},
    "ehr_access": {...}
}
Response  201
HideShow

201 Created is returned when a new EHR has been successfully created. The new EHR resource is returned in the body when the request’s Prefer header value is return=representation.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}
Body
{
    "system_id": {},
    "ehr_id": {},
    "ehr_status": "versioned ehr status uid",
    "ehr_acess": "versioned ehr access uid",
    "directory": {},
    "time_created", "..."
}
Response  400
HideShow

‘400 Bad Request’ is returned whenu nable to create a new EHR due to bad client Request, e.g. malformed syntax such as the ‘ehrId’ not a valid HIER_OBJECT_ID value.

Response  409
HideShow

Unable to create a new EHR due to a conflict with the current state of the resource. Can happen when the supplied ehrId already exists.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised to be performed.

Response  405
HideShow

405 Method Not Allowed is returned when an EHR with specified ehrId already exists.

Get EHR
GET/ehr/{ehrId}

Retrieve the EHR with the specified ehrId.

Example URI

GET http://www.openehr.org/api/ehr/ehrId
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

Response  200
HideShow

200 OK is returned when the EHR resource is successfully retrieved.

Headers
Content-Type: application/json
Body
{
    "system_id": {},
    "ehr_id": {},
    "ehr_status": "versioned ehr status uid",
    "ehr_acess": "versioned ehr access uid",
    "directory": {},
    "time_created", "...",
    ... // to be defined, possibly counts of compositions, contributions, etc.
}
Response  400
HideShow

400 Bad Request is returned when the request has invalid content such as an invalid ehrId value.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when an EHR with ehrId does not exist.

Delete EHR
DELETE/ehr/{ehrId}

This call is under discussion.

Mark the EHR as deleted by updating the associated EHR_STATUS and EHR_ACCESS as deleted. The request body contains commit_audit attribute to be used as the commit audit details for the deleted EHR_STATUS and EHR_ACCESS resources. Where an implementation requires additional attestation to authorise the deletion, this can be provided in the attestations attribute in the request.

Note: Some jurisdictions may require the service to physically delete the EHR and all its content. This operation may be used to implement this capability but the commit_audit and attestations must be retained using an alternative audit trail than the usual contribution audit details.

Example URI

DELETE http://www.openehr.org/api/ehr/ehrId
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

Request
HideShow
Body
{
    "commit_audit": {
        "description": "Commit audit description",
        "committer": { "@type": "PARTY_IDENTIFIED", 
            ... }
    },
    "attestations": { ... }
}
Response  204
HideShow

204 No Content is return when EHR is successfully deleted.

Response  400
HideShow

400 Bad Request is returned when the request has invalid content such as an invalid ehrId value.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when an EHR with ehrId does not exist.

EHR_STATUS

EHR_STATUS

Management of EHR_STATUS resources.

Get EHR_STATUS
GET/ehr/{ehrId}/ehr_status?versionSelector

Retrieve the EHR_STATUS associated with the EHR specified by ehrId. When the versionSelector parameter is provided, the EHR_STATUS version that existed at the specified version time is returned, otherwise the latest trunk version is returned. The versionSelector parameter may be an ISO8601 datetime string or symbolic value such as LATEST_TRUNK_VERSION.

Example URI

GET http://www.openehr.org/api/ehr/ehrId/ehr_status?versionSelector
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

versionSelector
string (optional) 

version time specifier

Response  200
HideShow

200 OK is return with the EHR_STATUS resource in the body when it is successfully retrieved.

Headers
Content-Type: application/json
Content-Location: /ehr/{ehrId}/ehr_status/{versionUid}
ETag: {versionUid}
Body
{
  "uid": "..",
  "subject": {},
  "is_queryable": true,
  "is_modifiable": true,
  "other_details": {}
}
Response  400
HideShow

400 Bad Request is returned when the request has invalid content such as an invalid ehrId or versionUid format.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found returned when EHR with ehrId does not exist or has been deleted or a version of an EHR_STATUS resource does not exist at the specified versionSelector.

Get EHR_STATUS by versionUid
GET/ehr/{ehrId}/ehr_status/{versionUid}

Retrieve the version of the EHR_STATUS associated with the specified ehrId and versionUid.

Example URI

GET http://www.openehr.org/api/ehr/ehrId/ehr_status/versionUid
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

versionUid
string (required) 

version UID

Response  200
HideShow

200 OK is return when the EHR_STATUS is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "uid": "..",
  "subject": {},
  "is_queryable": true,
  "is_modifiable": true,
  "other_details": {}
}
Response  400
HideShow

400 Bad Request is returned when the request has invalid parameters such as an invalid ehrId value.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when an EHR with ehrId does not exist or an EHR_STATUS with versionUid does not exist.

Update EHR_STATUS
PUT/ehr/{ehrId}/ehr_status

Update EHR_STATUS associated with the specified ehrId. The existing versionUid of EHR_STATUS resource must be specified in the Match-If header. The response will contain the updated EHR_STATUS resource when the Prefer header has a value of return=representation

Example URI

PUT http://www.openehr.org/api/ehr/ehrId/ehr_status
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

Request
HideShow
Headers
Content-Type: application/json
Match-If: {precedingVersionUid}
Prefer: return={representation|minimal}
Body
{
  "subject": {},
  "is_queryable": true,
  "is_modifiable": true,
  "other_details": {}
}
Response  200
HideShow

200 OK return when EHR_STATUS resource is successfully updated. The updated EHR_STATUS resource is returned in the body when prefer header value is return=representation.

Headers
Content-Location: /ehr/{ehrId}/ehr_status/{versionUid}
ETag: {versionUid}
Body
{
  "uid": "...",
  "subject": {},
  "is_queryable": true,
  "is_modifiable": true,
  "other_details": {}
}
Response  204
HideShow

204 No Content is returned when Prefer header is NOT set to return=representation.

Headers
Content-Location: /ehr/{ehrId}/ehr_status/{versionUid}
ETag: {versionUid}
Response  400
HideShow

400 Bad Request is returned when the request has invalid content such as an invalid ehrId format.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when EHR with ehrId does not exist or has been deleted or a version of an EHR_STATUS resource does not exist at the specified versionSelector.

Response  412
HideShow

412 Conflict is return when Match-If header doesn’t match the latest trunk version. Returns latest trunk version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/ehr_status/{versionUid}
ETag: {versionUid}

VERSIONED_EHR_STATUS

Management of VERSIONED_EHR_STATUS resources.

Get VERSIONED_EHR_STATUS
GET/ehr/{ehrId}/versioned_ehr_status

Retrieve VERSIONED_EHR_STATUS associated with an EHR specified by ehrId including its revision_history.

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_ehr_status
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

Response  200
HideShow

200 OK is return when the requested EHR’s VERSIONED_EHR_STATUS is successfully retrieved, which is provided in the body.

Headers
Content-Type: application/json
Body
{
    "uid": "xxx",
    "owner_id": "{ehrId}",
    "time_created": "ISO8601 timestamp",
    "revision_history": 
        { "items": [
            { "version_id": "",
                "audits" : [ {...} ]
            }]
}
}
Response  400
HideShow

400 Bad Request is returned when the request is invalid such as an invalid ehrId value.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when an EHR with ehrId does not exist.

Get EHR_STATUS version
GET/ehr/{ehrId}/versioned_ehr_status/version?{versionSelector}

Retrieve the VERSION of an EHR_STATUS associated with the specified ehrId and selected by versionSelector. When the versionSelector parameter is provided, the VERSION that existed at the specified version time is returned, otherwise the latest trunk version is returned. The versionSelector parameter may be an ISO8601 datetime string or symbolic value such as LATEST_TRUNK_VERSION.

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_ehr_status/version?versionSelector
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

versionSelector
string (optional) 

version time specifier

Response  200
HideShow

200 OK is return when the requested VERSION is successfully retrieved, which is provided in the body.

Headers
Content-Type: application/json
Content-Location: /ehr/{ehrId}/versioned_ehr_status/version/{versionUid}
Body
{
    "contribution": {...},
    "signature": "...",
    "commit_audit": {...},
    "uid": "...",
    "data": {
        "subject": {...},
        "is_modifiable": "...",
        "is_queryable": "...",
        "other_details": {...}
    }
}
Response  400
HideShow

400 Bad Request is returned when the request is invalid such as an invalid ehrId or versionSelector value.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when EHR with ehrId does not exist, deleted or when EHR_STATUS does not exist at the specified versionSelector.

Get EHR_STATUS version by uid
GET/ehr/{ehrId}/versioned_ehr_status/version/{versionUid}

Retrieve VERSION of an EHR_STATUS associated with the specified ehrId and versionUid.

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_ehr_status/version/versionUid
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

versionUid
string (required) 

version uid

Response  200
HideShow

200 OK is return when the requested VERSION is successfully retrieved.

Headers
Content-Type: application/json
Body
{
    "contribution": {...},
    "signature": "...",
    "commit_audit": {...},
    "uid": "...",
    "data": {
        "subject": {...},
        "is_modifiable": "...",
        "is_queryable": "...",
        "other_details": {...}
    }
}
Response  400
HideShow

400 Bad Request is returned when the request is invalid such as an invalid ehrId or versionUid format.

Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when an EHR with ehrId does not exist or EHR_STATUS with versionUid does not exist.

EHR_ACCESS

EHR_ACCESS

Get EHR_ACCESS by versionUid
GET/ehr/{ehrId}/ehr_access/{versionUid}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/ehr_access/versionUid
URI Parameters
HideShow
ehrId
string (required) 

EHR identifier

versionUid
string (required) 

version unique identifier

Response  200
HideShow

200 OK is returned when the EHR_ACCESS is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "uid": "...",
  "settings": {}
}
Response  401
HideShow

401 Unauthorized is returned when request is not authorised.

Response  404
HideShow

404 Not Found is returned when an EHR with ehrId does not exist or an EHR_STATUS with versionUid does not exist.

Get EHR_ACCESS
GET/ehr/{ehrId}/ehr_access{?versionSelector}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/ehr_access?versionSelector=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

versionSelector
string (optional) 

version time specifier

Response  200
HideShow
Headers
Content-Type: application/json
Content-Location: /ehr/{ehrId}/ehr_access/{versionUid}
ETag: {versionUid}
Body
{
  "uid": "...",
  "settings": {}
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Update an EHR_ACCESS
PUT/ehr/{ehrId}/ehr_access

Example URI

PUT http://www.openehr.org/api/ehr/ehrId/ehr_access
URI Parameters
HideShow
ehrId
string (required) 

EHR id

Request
HideShow
Headers
Content-Type: application/json
Match-If: {precedingVersionUid}
Prefer: return={representation/minimal}
Body
{
  "settings": {}
}
Response  200
HideShow

Returned when Prefer header is set to return=representation.

Headers
Content-Location: /ehr/{ehrId}/ehr_status/{versionUid}
ETag: {versionUid}
Body
{
  "uid": "...",
  "settings": {}
}
Response  204
HideShow

Returned when Prefer header is NOT set to return=representation.

Headers
Content-Location: /ehr/{ehrId}/ehr_access/{versionUid}
ETag: {versionUid}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/ehr_access/{versionUid}
ETag: {versionUid}

VERSIONED_EHR_ACCESS

Get a VERSIONED_EHR_ACCESS
GET/ehr/{ehrId}/versioned_ehr_access

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_ehr_access
URI Parameters
HideShow
ehrId
string (required) 

EHR id

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "uid": "xxx",
    "owner_id": "{ehrId}",
    "time_created": "ISO8601 timestamp",
    "version_count: 12,
    "all_version_ids": [
        "versioned_uid1",
        "versioned_uid2",
        ...
    ]
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Get an EHR_ACCESS version by versionUid
GET/ehr/{ehrId}/versioned_ehr_access/versions/{versionUid}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_ehr_access/versions/versionUid
URI Parameters
HideShow
ehrId
string (required) 

EHR id

versionUid
string (required) 

version UID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "contribution": {},
    "signature": "...",
    "commit_audit": {},
    "uid": "...",
    "data": {
        "settings": {},
    }
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Get an EHR_ACCESS version
GET/ehr/{ehrId}/versioned_ehr_access/version{?versionSelector}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_ehr_access/version?versionSelector=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

versionSelector
string (optional) 

version time specifier

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "contribution": {},
    "signature": "...",
    "commit_audit": {},
    "uid": "...",
    "data": {
        "settings": {},
    }
}
Response  204
HideShow

No VERSION at versionSelector.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Create a new EHR_ACCESS version
POST/ehr/{ehrId}/versioned_ehr_access/version

Example URI

POST http://www.openehr.org/api/ehr/ehrId/versioned_ehr_access/version
URI Parameters
HideShow
ehrId
string (required) 

EHR id

Request
HideShow
  • Body (application/json)

    {
          "commit_audit": {},
          "data": {
              "settings": {},
          }
      }
Headers
Match-If: {precedingVersionUid}
Prefer: return={representation/minimal}
Response  201
HideShow

New EHR_ACCESS version was created. Content body is only returned when Prefer header was set to return=representation otherwise only headers are returned.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}/versioned_ehr_access/versions/{versionUid}
ETag: {versionUid}
Body
{
  "uid": "...",
  "contribution": {},
  "signature": "...",
  "commit_audit": {},
  "data": {
    "subject": {},
    "is_modifiable": "...",
    "is_queryable": "...",
    "other_details": {}
  }
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with given id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/versioned_ehr_access/versions/{versionUid}
ETag: {versionUid}

DIRECTORY

Directory

Create a directory
POST/ehr/{ehrId}/directory

Example URI

POST http://www.openehr.org/api/ehr/ehrId/directory
URI Parameters
HideShow
ehrId
string (required) 

EHR id

Request
HideShow
  • Body (application/json)

    {
          "items": [...],
          "folders": [{}]
      }
Headers
Prefer: return={representation/minimal}
Response  201
HideShow

New directory was created. Content body is only returned when Prefer header has return=representation otherwise only headers are returned.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}/directory/{versionUid}
ETag: {versionUid}
Body
{
    "uid": "...",
    "items": [...],
    "folders": [{}]
}
Response  400
HideShow

Bad request - error creating a directory.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Update a directory
PUT/ehr/{ehrId}/directory

Example URI

PUT http://www.openehr.org/api/ehr/ehrId/directory
URI Parameters
HideShow
ehrId
string (required) 

EHR id

Request
HideShow
  • Body (application/json)

    {
          "items": [...],
          "folders": [{}]
      }
Headers
Match-If: {precedingVersionUid}
Prefer: return={representation/minimal}
Response  200
HideShow

Directory was updated. Returned when Prefer header is set to return=representation.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}/directory/{versionUid}
ETag: {versionUid}
Body
{
    "uid": "...",
    "items": [...],
    "folders": [{}]
}
Response  204
HideShow

Directory was updated. Returned when Prefer header is NOT set to return=representation.

Headers
Location: /ehr/{ehrId}/directory/{versionUid}
ETag: {versionUid}
Response  400
HideShow

Bad request - error when updating a directory.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/directory/{versionUid}
ETag: {versionUid}

Delete a directory
DELETE/ehr/{ehrId}/directory

Example URI

DELETE http://www.openehr.org/api/ehr/ehrId/directory
URI Parameters
HideShow
ehrId
string (required) 

EHR id

Request
HideShow
Headers
Match-If: {precedingVersionUid}
Response  204
HideShow

Directory was deleted.

Response  400
HideShow

Bad request - error deleting directory.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/directory/{versionUid}
ETag: {versionUid}

Get a directory or its sub-folder by versionUid
GET/ehr/{ehrId}/directory/{versionUid}{?path}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/directory/versionUid?path=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

versionUid
string (required) 

version UID

path
string (optional) 

path to a sub-folder

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "uid": "...",
    "items": [...],
    "folders": [{}]
}
Response  204
HideShow

No sub-folder at provided path.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id or no directory with specified versionUid.

Get a directory or its sub-folder
GET/ehr/{ehrId}/directory{?versionSelector,path}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/directory?versionSelector=&path=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

versionSelector
string (optional) 

version time specifier

path
string (optional) 

path to a sub-folder

Response  200
HideShow
Headers
Content-Type: application/json
Location: /ehr/{ehrId}/directory/{versionUid}
ETag: {versionUid}
Body
{
    "uid": "...",
    "items": [...],
    "folders": [{}]
}
Response  204
HideShow

EHR has no directory at versionSelector or no sub-folder at provided path.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

COMPOSITION

Composition

Get a composition by version uid
GET/ehr/{ehrId}/compositions/{versionUid}{?format}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/compositions/versionUid?format=
URI Parameters
HideShow
ehrId
string (required) 

EHR id.

versionUid
string (required) 

version UID

format
string (optional) 
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "@type": "COMPOSITION",
    "name": {
        "@type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR or no composition with the version uid.

Get a composition
GET/ehr/{ehrId}/compositions/{object_id}{?versionSelector,format}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/compositions/object_id?versionSelector=&format=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

object_id
string (required) 

VERSIONED COMPOSITION’s uid

versionSelector
string (optional) 

version time specifier

format
string (optional) 
Response  200
HideShow
Headers
Content-Type: application/json
Content-Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}
Body
{
    "@type": "COMPOSITION",
    "name": {
        "@type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Response  204
HideShow

No composition at specified versionSelector.

Headers
Content-Type: application/json
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR or no composition with the given object id.

Create a new composition
POST/ehr/{ehrId}/compositions{?format}

Example URI

POST http://www.openehr.org/api/ehr/ehrId/compositions?format=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

format
string (optional) 
Request
HideShow
  • Body (application/json)

    {
          "@type": "COMPOSITION",
          "name": {
              "@type": "DV_TEXT",
              "value": "Vital Signs"
          },
          ...
      }
Headers
Prefer: return={representation/minimal}
Response  201
HideShow

New composition was created. Content body is only returned when Prefer header has return=representation otherwise only headers are returned.

Headers
Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}
Body
{
    "@type": "COMPOSITION",
    "name": {
        "@type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Response  400
HideShow

Bad request: composition validation errors.

Body
{
  "message": "Error message",
  "validationErrors": [
    "error1",
    "error2"
  ]
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Update or create a composition
PUT/ehr/{ehrId}/compositions/{object_id}{?format}

This call can be used to update an existing composition (identified by {objectId}) or to create a new one with the supplied {objectId} instead of a server assigned one. In case of an update Match-If header might be required.

Example URI

PUT http://www.openehr.org/api/ehr/ehrId/compositions/object_id?format=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

object_id
string (required) 

object id of the composition to update or create with this id

format
string (optional) 

optional format of the composition (when ommitted canonical openEHR is assumed)

Request
HideShow
  • Body (application/json)

    {
          "@type": "COMPOSITION",
          "name": {
              "@type": "DV_TEXT",
              "value": "Vital Signs"
          },
          ...
      }
Headers
Match-If: {precedingVersionUid}
Prefer: return={representation/minimal}
Response  200
HideShow

Returned when Prefer header is set to return=representation.

Headers
Content-Type: application/json
Content-Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}
Body
{
    "@type": "COMPOSITION",
    "name": {
        "@type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Response  204
HideShow

Returned when Prefer header is NOT set to return=representation.

Headers
Content-Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}
Response  400
HideShow

Bad request: composition validation errors.

Body
{
  "message": "Error message",
  "validationErrors": [
    "error1",
    "error2"
  ]
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id or no composition with the given object id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/ehr_status/{versionUid}
ETag: {versionUid}

Delete a composition
DELETE/ehr/{ehrId}/compositions/{object_id}

Example URI

DELETE http://www.openehr.org/api/ehr/ehrId/compositions/object_id
URI Parameters
HideShow
ehrId
string (required) 

EHR id

object_id
string (required) 

object id of the composition to delete

Request
HideShow
Headers
Match-If: {precedingVersionUid}
Response  204
HideShow

Composition was deleted.

Headers
Content-Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}
Response  400
HideShow

Bad request.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id or no composition with the given object id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}

Update a composition directly
PUT/compositions/{objectId}{?format}

Example URI

PUT http://www.openehr.org/api/compositions/objectId?format=
URI Parameters
HideShow
objectId
string (required) 

object id of the composition to update

format
string (optional) 

optional format of the composition (when ommitted canonical openEHR is assumed)

Request
HideShow
  • Body (application/json)

    {
          "@type": "COMPOSITION",
          "name": {
              "@type": "DV_TEXT",
              "value": "Vital Signs"
          },
          ...
      }
Headers
Match-If: {precedingVersionUid}
Prefer: return={representation/minimal}
Response  200
HideShow

Returned when Prefer header is set to return=representation.

Headers
Content-Type: application/json
Content-Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}
Body
{
    "@type": "COMPOSITION",
    "name": {
        "@type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Response  204
HideShow

Returned when Prefer header is NOT set to return=representation.

Headers
Content-Location: /ehr/{ehrId}/compositions/{versionUid}
ETag: {versionUid}
Response  400
HideShow

Bad request: composition validation errors.

Headers
Content-Type: application/json
Body
{
  "message": "Error message",
  "validationErrors": [
    "error1",
    "error2"
  ]
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id or no composition with the given object id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/ehr_status/{versionUid}
ETag: {versionUid}

Delete a composition directly
DELETE/compositions/{objectId}

Example URI

DELETE http://www.openehr.org/api/compositions/objectId
URI Parameters
HideShow
objectId
string (required) 

object id of the composition to delete

Request
HideShow
Headers
Match-If: {precedingVersionUid}
Response  204
HideShow

Composition was deleted.

Headers
Content-Location: /compositions/{versionUid}
ETag: {versionUid}
Response  400
HideShow

Bad request.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id or no composition with the given object id.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /compositions/{versionUid}
ETag: {versionUid}

Get a composition by version uid directly
GET/compositions/{versionUid}{?format}

Example URI

GET http://www.openehr.org/api/compositions/versionUid?format=
URI Parameters
HideShow
versionUid
string (required) 

version uid

format
string (optional) 
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "@type": "COMPOSITION",
    "name": {
        "@type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No composition with the version uid.

Get a composition directly
GET/compositions/{objectId}{?versionSelector,format}

Example URI

GET http://www.openehr.org/api/compositions/objectId?versionSelector=&format=
URI Parameters
HideShow
objectId
string (required) 

VERSIONED_COMPOSITION’s uid

versionSelector
string (optional) 

version time specifier

format
string (optional) 
Response  200
HideShow
Headers
Content-Type: application/json
Content-Location: /compositions/{versionUid}
ETag: {versionUid}
Body
{
    "@type": "COMPOSITION",
    "name": {
        "@type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Response  204
HideShow

No composition at specified versionSelector.

Headers
Content-Type: application/json
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No composition with the given object id.

Versioned Composition

Create a new versioned composition
POST/ehr/{ehrId}/versioned_compositions

Example URI

POST http://www.openehr.org/api/ehr/ehrId/versioned_compositions
URI Parameters
HideShow
ehrId
string (required) 

EHR id

Request
HideShow
Headers
Prefer: return={representation/minimal}
Response  201
HideShow

New versioned composition was created. Content body is only returned when Prefer header has return=representation otherwise only headers are returned.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}/versioned_compositions/{uid}
Body
{
  "uid": "xxx",
  "owner_id": "{ehrId}",
  "time_created": "ISO8601 timestamp"
}
Response  400
HideShow

Bad request - when VERSIONED_COMPOSITION with the given uid already exists.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Create a new versioned composition with supplied uid
PUT/ehr/{ehrId}/versioned_compositions/{uid}

Example URI

PUT http://www.openehr.org/api/ehr/ehrId/versioned_compositions/uid
URI Parameters
HideShow
ehrId
string (required) 

EHR id

uid
string (required) 

VERSIONED_COMPOSITION uid

Request
HideShow
Headers
Prefer: return={representation/minimal}
Response  201
HideShow

New versioned composition was created. Content body is only returned when Prefer header has return=representation otherwise only headers are returned.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}/versioned_compositions/{uid}
Body
{
  "uid": "xxx",
  "owner_id": "{ehrId}",
  "time_created": "ISO8601 timestamp"
}
Response  400
HideShow

Bad request - when VERSIONED_COMPOSITION with the given uid already exists.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Get a versioned composition
GET/ehr/{ehrId}/versioned_compositions/{uid}

Gets a complete VERSIONED_COMPOSITION.

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_compositions/uid
URI Parameters
HideShow
ehrId
string (required) 

EHR id

uid
string (required) 

VERSIONED_COMPOSITION’s uid

Response  200
HideShow
Headers
Content-Type: application/json
Location: /ehr/{ehrId}/versioned_compositions/{uid}
Body
{
    "uid": "xxx",
    "owner_id": "{ehrId}",
    "time_created": "ISO8601 timestamp",
    "version_count: 12,
    "all_version_ids": [
        "versioned_uid1",
        "versioned_uid2",
        ...
    ]
}
Response  400
HideShow

Bad request - when VERSIONED_COMPOSITION with the given uid already exists.

Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id.

Create a new composition version
POST/ehr/{ehrId}/versioned_compositions/{uid}/version{?format}

Example URI

POST http://www.openehr.org/api/ehr/ehrId/versioned_compositions/uid/version?format=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

uid
string (required) 

VERSIONED_COMPOSITION’s uid

format
string (optional) 

optional format of the composition (when ommitted canonical openEHR is assumed)

Request
HideShow
  • Body (application/json)

    {
          "commit_audit": {},
          "data": {
              "@type": "COMPOSITION",
              "name": {
                  "@type": "DV_TEXT",
                  "value": "Vital Signs"
              }
              ...
          }
      }
Headers
Match-If: {precedingVersionUid}
Prefer: return={representation/minimal}
Response  201
HideShow

New composition version was created. Content body is only returned when Prefer header was set to return=representation otherwise only headers are returned.

Headers
Content-Type: application/json
Location: /ehr/{ehrId}/versioned_compositions/{uid}/versions/{versionUid}
ETag: {versionUid}
Body
{
    "contribution": {},
    "signature": "...",
    "commit_audit": {},
    "uid": "...",
    "data": {
        "@type": "COMPOSITION",
        "name": {
            "@type": "DV_TEXT",
            "value": "Vital Signs"
        }
        ...
    }
}
Response  400
HideShow

Bad request: composition validation errors.

Body
{
  "message": "Error message",
  "validationErrors": [
    "error1",
    "error2"
  ]
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id or no VERSIONED_COMPOSITION with uid.

Response  412
HideShow

Match-If header doesn’t match the last version. Returns last version in the Content-Location and ETag headers.

Headers
Content-Location: /ehr/{ehrId}/versioned_compositions/{uid}/versions/{versionUid}
ETag: {versionUid}

Get a composition version by versionUid
GET/ehr/{ehrId}/versioned_compositions/{uid}/version/{versionUid}{?format}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_compositions/uid/version/versionUid?format=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

uid
string (required) 

VERSIONED_COMPOSITION’s uid

versionUid
string (required) 

version uid

format
string (optional) 

optional format of the composition (when ommitted canonical openEHR is assumed)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "contribution": {},
    "signature": "...",
    "commit_audit": {},
    "uid": "...",
    "data": {
        "@type": "COMPOSITION",
        "name": {
            "@type": "DV_TEXT",
            "value": "Vital Signs"
        }
        ...
    }
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id, no VERSIONED_COMPOSITION with uid or no version with versionUid.

Get a composition version
GET/ehr/{ehrId}/versioned_compositions/{uid}/version{?versionSelector,format}

Example URI

GET http://www.openehr.org/api/ehr/ehrId/versioned_compositions/uid/version?versionSelector=&format=
URI Parameters
HideShow
ehrId
string (required) 

EHR id

uid
string (required) 

VERSIONED_COMPOSITION’s uid

versionSelector
string (optional) 

version time specifier

format
string (optional) 

optional format of the composition (when ommitted canonical openEHR is assumed)

Response  200
HideShow
Headers
Content-Type: application/json
Location: /ehr/{ehrId}/versioned_compositions/{uid}/versions/{versionUid}
ETag: {versionUid}
Body
{
    "contribution": {},
    "signature": "...",
    "commit_audit": {},
    "uid": "...",
    "data": {
        "@type": "COMPOSITION",
        "name": {
            "@type": "DV_TEXT",
            "value": "Vital Signs"
        }
        ...
    }
}
Response  401
HideShow

Unauthorized.

Response  404
HideShow

No EHR with the given id, no VERSIONED_COMPOSITION with uid or no version with versionUid.

QUERY

Querying

Get AQL query results
GET/query/?aql={aql}

Execute an AQL query as given by the aql parameter.

select
a_a/data[at0002]/events[at0003]/time as When,
a_a/data[at0002]/events[at0003]/data[at0001]/items[at0004]/value as Temperature
from EHR e contains COMPOSITION a CONTAINS OBSERVATION a_a[openEHR-EHR-OBSERVATION.body_temperature.v1]
order by a_a/data[at0002]/events[at0003]/time desc
offset 0 limit 2

Example URI

GET http://www.openehr.org/api/query/?aql=aql
URI Parameters
HideShow
aql
string (required) 

The aql to be executed

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "@type": "raw",
  "@schemaversion": "0.1.0",
  "@created": "2016-06-22T07:54:04.758+02:00",
  "@generator": "<The resultset generator>",
  "totalResults": 2,
  "columns": [
    {
      "name": "When",
      "path": "/data[at0002]/events[at0003]/time"
    },
    {
      "name": "Temperature",
      "path": "/data[at0002]/events[at0003]/data[at0001]/items[at0004]/value"
    }
  ],
  "rows": [
    [
      {
        "@type": "DV_DATE_TIME",
        "value": "2016-06-08T11:02:47+02:00"
      },
      {
        "@type": "DV_QUANTITY",
        "magnitude": 38,
        "units": "°C"
      }
    ],
    [
      {
        "@type": "DV_DATE_TIME",
        "value": "2016-06-05T08:53:36+02:00"
      },
      {
        "@type": "DV_QUANTITY",
        "magnitude": 37,
        "units": "Cel"
      }
    ]
  ]
}

Get query results
POST/query/aql

Execute an AQL query.

NOTE: we might add a header to indicate which EHR to execute against to allow systems that need to route based of EHR id to do so without having to analyze the request body.

Example URI

POST http://www.openehr.org/api/query/aql
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "aql": "SELECT ....",
    "aqlParameters": {
        "parameter-name": "parameter-value",...
    },
    "offset": 999,
    "fetch": 888,
    // possibly more, TBD
}
Response  200
HideShow
Body
{
    "metaData": {
        "hits": 199,
        ...
    },
    "resultSet": [
        {
            "unit": "°C",
            "temperature": 38.8
        },
        {
            "unit": "°C",
            "temperature": 38.8
        },
        {
            "unit": "°C",
            "temperature": 38.8
        }
    ],
    "executedAql": "aql with replaced parameters",
}

Generated by aglio on 30 Jun 2016