REST API specification:OverviewEhrQueryDefinitions

EHR API

Release
1.0.2
Status
STABLE
Date
24 Apr 2021
API Endpoint
{baseUrl}/v1/ehr
© 2003 - 2021 The openEHR Foundation
The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform 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.2
4.2 SPECITS-41: Add double quotes to ETag and If-Match headers S Iancu 21 Mar 2021
4.1 SPECITS-49: Describing Resource Identification; add clarification over getting COMPOSITIONs by with `version_uid` vs `versioned_object_uid` J Smolka, M Polajnar, S Iancu 08 Mar 2021
4.0 SPECITS-52: Fix wrong example on revision history of the VERSIONED_COMPOSITION and VERSIONED_EHR_STATUS J Smolka, S Iancu 06 Mar 2021
Release-1.0.1
3.2 SPECITS-38: Fix response status code for semantic validation errors (fixes also SPECPR-298) P Pazos, S Iancu 01 Oct 2019
3.1 SPECITS-40: Fix and improve documentation on EHR (fixes also SPECPR-312) P Pazos, S Iancu 28 Sep 2019
3.0 SPECITS-32: Fix typos and minor documentary errors (fixes SPECPR-253, SPECPR-255, SPECPR-298, SPECPR-333, SPECPR-337) 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

EHR

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

EHR

Management of EHRs.

POST {baseUrl}/v1/ehr
Requestsexample 1
Headers
Prefer: return={representation|minimal}
Body
{
  "_type": "EHR_STATUS",
  "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  "name": {
    "value": "EHR Status"
  },
  "subject": {
    "external_ref": {
      "id": {
        "_type": "GENERIC_ID",
        "value": "ins01",
        "scheme": "id_scheme"
      },
      "namespace": "examples",
      "type": "PERSON"
    }
  },
  "is_modifiable": true,
  "is_queryable": true
}
Responses201400409

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

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398
ETag: "7d44b88c-4199-4bad-97dc-d78268e01398"
Body
{
  "system_id": {
    "value": "d60e2348-b083-48ce-93b9-916cef1d3a5a"
  },
  "ehr_id": {
    "value": "7d44b88c-4199-4bad-97dc-d78268e01398"
  },
  "ehr_status": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_STATUS"
  },
  "ehr_access": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "59a8d0ac-140e-4feb-b2d6-af99f8e68af8::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_ACCESS"
  },
  "time_created": {
    "value": "2015-01-20T19:30:22.765+01:00"
  }
}

400 Bad Request is returned when the request body (if provided) could not be parsed.

409 Conflict Unable to create a new EHR due to a conflict with an already existing EHR with the same subject id, namespace pair.

Create EHR
POST/ehr

Create a new EHR with an auto-generated identifier.

An EHR_STATUS resource needs to be always created and committed in the new EHR. This resource MAY be also supplied by the client as the request body. If not supplied, a default EHR_STATUS will be used by the service with following attributes:

  • is_queryable: true

  • is_modifiable: true

  • subject: a PARTY_SELF object

All other required EHR attributes and resources will be automatically created as needed by the EHR creation semantics.

PUT {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398
Requestsexample 1
Headers
Prefer: return={representation|minimal}
Body
{
  "_type": "EHR_STATUS",
  "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  "name": {
    "value": "EHR Status"
  },
  "subject": {
    "external_ref": {
      "id": {
        "_type": "GENERIC_ID",
        "value": "ins01",
        "scheme": "id_scheme"
      },
      "namespace": "examples",
      "type": "PERSON"
    }
  },
  "is_modifiable": true,
  "is_queryable": true
}
Responses201400409

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

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398
ETag: "7d44b88c-4199-4bad-97dc-d78268e01398"
Body
{
  "system_id": {
    "value": "d60e2348-b083-48ce-93b9-916cef1d3a5a"
  },
  "ehr_id": {
    "value": "7d44b88c-4199-4bad-97dc-d78268e01398"
  },
  "ehr_status": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_STATUS"
  },
  "ehr_access": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "59a8d0ac-140e-4feb-b2d6-af99f8e68af8::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_ACCESS"
  },
  "time_created": {
    "value": "2015-01-20T19:30:22.765+01:00"
  }
}

400 Bad Request is returned when the request has invalid ehr_id format or invalid content (e.g. either the body of the request could not be read, or converted to an EHR_STATUS object).

409 Conflict Unable to create a new EHR due to a conflict with an already existing EHR. Can happen when the supplied ehr_id is already used by an existing EHR.

Create EHR with id
PUT/ehr/{ehr_id}

Create a new EHR with the specified ehr_id identifier.

The value of the ehr_id unique identifier MUST be valid
HIER_OBJECT_ID value. It is strongly RECOMMENDED that an UUID always be used for this.

An EHR_STATUS resource needs to be always created and committed in the new EHR. This resource MAY be also supplied by the client as the request body. If not supplied, a default EHR_STATUS will be used by the service with following attributes:

  • is_queryable: true

  • is_modifiable: true

  • subject: a PARTY_SELF object

All other required EHR attributes and resources will be automatically created as needed by the EHR creation semantics.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

An UUID as a user specified EHR identifier

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398
Responses200404

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

Headers
Content-Type: application/json
Body
{
  "system_id": {
    "value": "d60e2348-b083-48ce-93b9-916cef1d3a5a"
  },
  "ehr_id": {
    "value": "7d44b88c-4199-4bad-97dc-d78268e01398"
  },
  "ehr_status": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_STATUS"
  },
  "ehr_access": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "59a8d0ac-140e-4feb-b2d6-af99f8e68af8::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_ACCESS"
  },
  "time_created": {
    "value": "2015-01-20T19:30:22.765+01:00"
  }
}

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

Get EHR summary by id
GET/ehr/{ehr_id}

Retrieve the EHR with the specified ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

GET {baseUrl}/v1/ehr?subject_id=ins01&subject_namespace=examples
Responses200404

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

Headers
Content-Type: application/json
Body
{
  "system_id": {
    "value": "d60e2348-b083-48ce-93b9-916cef1d3a5a"
  },
  "ehr_id": {
    "value": "7d44b88c-4199-4bad-97dc-d78268e01398"
  },
  "ehr_status": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_STATUS"
  },
  "ehr_access": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "59a8d0ac-140e-4feb-b2d6-af99f8e68af8::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_ACCESS"
  },
  "time_created": {
    "value": "2015-01-20T19:30:22.765+01:00"
  }
}

404 Not Found is returned when an EHR with supplied subject parameters does not exist.

Get EHR summary by subject id
GET/ehr{?subject_id,subject_namespace}

Retrieve the EHR with the specified subject_id and subject_namespace. These subject parameters will be matched against EHR’s EHR_STATUS.subject.external_ref.id.value and EHR_STATUS.subject.external_ref.namespace values.

URI Parameters
HideShow
subject_id
string (required) Example: ins01

subject id

subject_namespace
string (required) Example: examples

id namespace

EHR_STATUS

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

EHR_STATUS

Management of EHR_STATUS resource.

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/ehr_status?version_at_time=2015-01-20T19:30:22.765+01:00
Responses200400404

200 OK is returned when the requested EHR_STATUS is successfully retrieved.

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/ehr_status/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
Body
{
  "_type": "EHR_STATUS",
  "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  "name": {
    "value": "EHR Status"
  },
  "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
  },
  "subject": {
    "external_ref": {
      "id": {
        "_type": "HIER_OBJECT_ID",
        "value": "324a4b23-623d-4213-cc1c-23f233b24234"
      },
      "namespace": "DEMOGRAPHIC",
      "type": "PERSON"
    }
  },
  "other_details": {
    "_type": "ITEM_TREE",
    "archetype_node_id": "at0001",
    "name": {
      "value": "Details"
    },
    "items": []
  },
  "is_modifiable": true,
  "is_queryable": true
}

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

404 Not Found returned when EHR with ehr_id does not exist or a version of an EHR_STATUS resource does not exist at the specified version_at_time.

Get EHR_STATUS version by time
GET/ehr/{ehr_id}/ehr_status{?version_at_time}

Retrieves a version of the EHR_STATUS associated with the EHR identified by ehr_id. If version_at_time is supplied, retrieves the version extant at specified time, otherwise retrieves the latest EHR_STATUS version.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

version_at_time
string (optional) Example: 2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format

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

200 OK is returned when the requested EHR_STATUS is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "_type": "EHR_STATUS",
  "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  "name": {
    "value": "EHR Status"
  },
  "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
  },
  "subject": {
    "external_ref": {
      "id": {
        "_type": "HIER_OBJECT_ID",
        "value": "324a4b23-623d-4213-cc1c-23f233b24234"
      },
      "namespace": "DEMOGRAPHIC",
      "type": "PERSON"
    }
  },
  "other_details": {
    "_type": "ITEM_TREE",
    "archetype_node_id": "at0001",
    "name": {
      "value": "Details"
    },
    "items": []
  },
  "is_modifiable": true,
  "is_queryable": true
}

404 Not Found is returned when an EHR with ehr_id does not exist or when an EHR_STATUS with version_uid does not exist.

Get EHR_STATUS by version id
GET/ehr/{ehr_id}/ehr_status/{version_uid}

Retrieves a particular version of the EHR_STATUS identified by version_uid and associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

version_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2

VERSION identifier taken from VERSION.uid.value

PUT {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/ehr_status
Requestsexample 1
Headers
Content-Type: application/json
If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Prefer: return={representation|minimal}
Body
{
  "_type": "EHR_STATUS",
  "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  "name": {
    "value": "EHR Status"
  },
  "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
  },
  "subject": {
    "external_ref": {
      "id": {
        "_type": "HIER_OBJECT_ID",
        "value": "324a4b23-623d-4213-cc1c-23f233b24234"
      },
      "namespace": "DEMOGRAPHIC",
      "type": "PERSON"
    }
  },
  "other_details": {
    "_type": "ITEM_TREE",
    "archetype_node_id": "at0001",
    "name": {
      "value": "Details"
    },
    "items": []
  },
  "is_modifiable": true,
  "is_queryable": true
}
Responses200204400404412

200 OK is returned when the EHR_STATUS is successfully updated, and the updated resource is returned in the body when Prefer header value is return=representation.

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/ehr_status/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
Body
{
  "_type": "EHR_STATUS",
  "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  "name": {
    "value": "EHR Status"
  },
  "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
  },
  "subject": {
    "external_ref": {
      "id": {
        "_type": "HIER_OBJECT_ID",
        "value": "324a4b23-623d-4213-cc1c-23f233b24234"
      },
      "namespace": "DEMOGRAPHIC",
      "type": "PERSON"
    }
  },
  "other_details": {
    "_type": "ITEM_TREE",
    "archetype_node_id": "at0001",
    "name": {
      "value": "Details"
    },
    "items": []
  },
  "is_modifiable": true,
  "is_queryable": true
}

204 No Content is returned when Prefer header is missing or is set to return=minimal.

Headers
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/ehr_status/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"

400 Bad Request is returned when the request has invalid content.

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

412 Precondition Failed is returned when If-Match request header doesn’t match the latest version on the service side. Returns also latest version_uid in the Location and ETag headers.

Headers
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/ehr_status/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::3
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::3"

Update EHR_STATUS
PUT/ehr/{ehr_id}/ehr_status

Updates EHR_STATUS associated with the EHR identified by ehr_id. The existing latest version_uid of EHR_STATUS resource (i.e. the preceding_version_uid) must be specified in the If-Match header. The response will contain the updated EHR_STATUS resource when the Prefer header has a value of return=representation

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

VERSIONED_EHR_STATUS

Management of VERSIONED_EHR_STATUS resource.

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/versioned_ehr_status
Responses200404

200 OK is returned when the requested VERSIONED_EHR_STATUS is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "_type": "VERSIONED_EHR_STATUS",
  "uid": {
    "value": "8849182c-82ad-4088-a07f-48ead4180515"
  },
  "owner_id": {
    "id": {
      "_type": "HIER_OBJECT_ID",
      "value": "7d44b88c-4199-4bad-97dc-d78268e01398"
    },
    "namespace": "local",
    "type": "EHR"
  },
  "time_created": {
    "value": "2015-01-20T19:30:22.765+01:00"
  }
}

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

Get versioned EHR_STATUS
GET/ehr/{ehr_id}/versioned_ehr_status

Retrieves a VERSIONED_EHR_STATUS associated with an EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/versioned_ehr_status/revision_history
Responses200404

200 OK is returned when the requested VERSIONED_EHR_STATUS revision history is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "_type": "REVISION_HISTORY",
  "items": [
    {
      "version_id": {
        "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
      },
      "audits": [
        {
          "system_id": "d60e2348-b083-48ce-93b9-916cef1d3a5a",
          "time_committed": {
            "value": "2015-01-20T19:30:22.765+01:00"
          },
          "change_type": {
            "value": "creation",
            "defining_code": {
              "terminology_id": {
                "value": "openehr"
              },
              "code_string": "249"
            }
          },
          "description": {
            "value": "An optional description string"
          },
          "committer": {
            "_type": "PARTY_IDENTIFIED",
            "name": "A user name"
          }
        }
      ]
    }
  ]
}

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

Get versioned EHR_STATUS revision history
GET/ehr/{ehr_id}/versioned_ehr_status/revision_history

Retrieves revision history of the VERSIONED_EHR_STATUS associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/versioned_ehr_status/version?version_at_time=2015-01-20T19:30:22.765+01:00
Responses200400404

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

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/versioned_ehr_status/version/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
  "_type": "ORIGINAL_VERSION",
  "uid": "OBJECT_VERSION_ID",                  /* _ehr_status_uid_::_system_id_::1 _system_id_ is the ID of the system from which the EHR was created */
  "contribution": "OBJECT_REF",
  "signature": "String",                       /* optional */
  "data": {
    "_type": "EHR_STATUS",
    "subject": {
      "external_ref": {
        "namespace": "DEMOGRAPHIC",
        "type": "PERSON",
        "id": {
          "_type": "HIER_OBJECT_ID",
          "value": "_valid_root_uid_::_extension_" /* root can be UUID or OID, UUID preferred '::_extension_' is optional */
        }
      }
    }
    "is_queryable": true,
    "is_modifiable": true,
    "other_details": {                         /* optional, ITEM_STRUCTURE, archetypable */
      "_type": "ITEM_TREE",
      "items": {
        ...
      }
    }
  },
  "commit_audit": {                            /* the time committed attribute is set by the server */
    "system_id": "_a_string_id_",              /* same as the container version.uid.system_id */
    "change_type": {
      "value": "creation",
      "terminology_id": {
        "value": "openehr"
      },
      "code_string": "249"
    },
    "description": "optional description"
  },
  "attestations": [
    {
      "system_id": "String",
      "time_committed": "DV_DATE_TIME",
      "description": "String"                  /* optional */
      "reason": "DV_TEXT",
      "proof": "String",                       /* optional */
      "is_pending": "Boolean"
    },
    {...},
    {...}
  ]
}

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

404 Not Found is returned when an EHR with ehr_id does not exist or when an EHR_STATUS does not exist at the specified version_at_time.

Get versioned EHR_STATUS version by time
GET/ehr/{ehr_id}/versioned_ehr_status/version{?version_at_time}

Retrieves a VERSION from the VERSIONED_EHR_STATUS associated with the EHR identified by ehr_id. If version_at_time is supplied, retrieves the VERSION extant at specified time, otherwise retrieves the latest VERSION.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

version_at_time
string (optional) Example: 2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format

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

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

Headers
Content-Type: application/json
Body
{
  "_type": "ORIGINAL_VERSION",
  "uid": "OBJECT_VERSION_ID",                  /* _ehr_status_uid_::_system_id_::1 _system_id_ is the ID of the system from which the EHR was created */
  "contribution": {                            /* does not include reference to other versions, even that is mandatory in the IM */
    "uid": "HIER_OBJECT_ID",
    "audit": {
      "system_id": "String",
      "time_committed": "DV_DATE_TIME",
      "description": "String"                  /* optional */
    }
  },
  "signature": "String",                       /* optional */
  "data": {
    "_type": "EHR_STATUS",
    "subject": {
      "external_ref": {
        "namespace": "DEMOGRAPHIC",
        "type": "PERSON",
        "id": {
          "_type": "HIER_OBJECT_ID",
          "value": "_valid_root_uid_::_extension_" /* root can be UUID or OID, UUID preferred '::_extension_' is optional */
        }
      }
    }
    "is_queryable": true,
    "is_modifiable": true,
    "other_details": {                         /* optional, ITEM_STRUCTURE, archetypable */
      "_type": "ITEM_TREE",
      "items": {
        ...
      }
    }
  },
  "commit_audit": {                            /* the time committed attribute is set by the server */
    "system_id": "_a_string_id_",              /* same as the container version.uid.system_id */
    "change_type": {
      "value": "creation",
      "terminology_id": {
        "value": "openehr"
      },
      "code_string": "249"
    },
    "description": "optional description"
  },
  "attestations": [
    {
      "system_id": "String",
      "time_committed": "DV_DATE_TIME",
      "description": "String"                  /* optional */
      "reason": "DV_TEXT",
      "proof": "String",                       /* optional */
      "is_pending": "Boolean"
    },
    {...},
    {...}
  ]
}

404 Not Found is returned when an EHR with ehr_id does not exist or when an EHR_STATUS with version_uid does not exist.

Get versioned EHR_STATUS version by id
GET/ehr/{ehr_id}/versioned_ehr_status/version/{version_uid}

Retrieves a VERSION identified by version_uid of an EHR_STATUS associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

version_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

VERSION identifier taken from VERSION.uid.value

COMPOSITION

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

COMPOSITION

Management of COMPOSITION resources.

POST {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition
Requestsexample1wrong type
Headers
Content-Type: application/json
Prefer: return={representation|minimal}
Body
{
  "_type": "COMPOSITION",
  "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  "name": {
    "value": "Vital Signs"
  },
  "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
  },
  "archetype_details": {
    "archetype_id": {
      "value": "openEHR-EHR-COMPOSITION.encounter.v1"
    },
    "template_id": {
      "value": "Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747"
    },
    "rm_version": "1.0.2"
  },
  "language": {
    "terminology_id": {
      "value": "ISO_639-1"
    },
    "code_string": "en"
  },
  "territory": {
    "terminology_id": {
      "value": "ISO_3166-1"
    },
    "code_string": "NL"
  },
  "category": {
    "value": "event",
    "defining_code": {
      "terminology_id": {
        "value": "openehr"
      },
      "code_string": "433"
    }
  },
  "composer": {
    "_type": "PARTY_IDENTIFIED",
    "external_ref": {
      "id": {
        "_type": "GENERIC_ID",
        "value": "16b74749-e6aa-4945-b760-b42bdc07098a"
      },
      "namespace": "openEHRSys.example.com",
      "type": "PERSON"
    },
    "name": "A name"
  },
  "context": {
    "start_time": {
      "value": "2014-11-18T09:50:35.000+01:00"
    },
    "setting": {
      "value": "other care",
      "defining_code": {
        "terminology_id": {
          "value": "openehr"
        },
        "code_string": "238"
      }
    }
  },
  "content": []
}
Responses201400404422

201 Created is returned when the 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: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
  "_type": "COMPOSITION",
  "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  "name": {
    "value": "Vital Signs"
  },
  "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
  },
  "archetype_details": {
    "archetype_id": {
      "value": "openEHR-EHR-COMPOSITION.encounter.v1"
    },
    "template_id": {
      "value": "Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747"
    },
    "rm_version": "1.0.2"
  },
  "language": {
    "terminology_id": {
      "value": "ISO_639-1"
    },
    "code_string": "en"
  },
  "territory": {
    "terminology_id": {
      "value": "ISO_3166-1"
    },
    "code_string": "NL"
  },
  "category": {
    "value": "event",
    "defining_code": {
      "terminology_id": {
        "value": "openehr"
      },
      "code_string": "433"
    }
  },
  "composer": {
    "_type": "PARTY_IDENTIFIED",
    "external_ref": {
      "id": {
        "_type": "GENERIC_ID",
        "value": "16b74749-e6aa-4945-b760-b42bdc07098a"
      },
      "namespace": "openEHRSys.example.com",
      "type": "PERSON"
    },
    "name": "A name"
  },
  "context": {
    "start_time": {
      "value": "2014-11-18T09:50:35.000+01:00"
    },
    "setting": {
      "value": "other care",
      "defining_code": {
        "terminology_id": {
          "value": "openehr"
        },
        "code_string": "238"
      }
    }
  },
  "content": []
}

400 Bad Request is returned when the request has invalid ehr_id or invalid content (e.g. content could not be converted to a valid COMPOSITION object)

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

422 Unprocessable Entity is returned when the content could be converted to a COMPOSITION, but there are semantic validation errors, such as the underlying template is not known or is not validating the supplied COMPOSITION).

Headers
Content-Type: application/json
Body
{
  "_type": "XYZ",
  "value": "Vital Signs"
}
Responses400

400 Bad Request either the body of the request could not be read (or converted to a COMPOSITION object) or there were COMPOSITION validation errors.

Body
{ /* see overview */
    "message": "Error message",
    "validationErrors": [
        "error1", "error2"
    ]
}

Create composition
POST/ehr/{ehr_id}/composition

Creates the first version of a new COMPOSITION in the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

PUT {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515
Requestsexample1wrong typenot foundversion conflict
Headers
Content-Type: application/json
Prefer: return=representation
If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
    "_type": "COMPOSITION",
    "name": {
        "_type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Responses200422

200 OK is returned when the COMPOSITION is successfully updated and the updated resource is returned in the body when Prefer header value is return=representation.

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
Body
{
    "_type": "COMPOSITION",
    "name": {
        "_type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}

422 Unprocessable Entity is returned when the content could be converted to a COMPOSITION, but there are semantic validation errors, such as the underlying template is not known or is not validating the supplied COMPOSITION).

Headers
Content-Type: application/json
If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
  "_type": "XYZ",
  "value": "Vital Signs"
}
Responses400

400 Bad Request is returned when the request has invalid ehr_id or invalid content (e.g. either the body of the request could not be read, or converted to a valid COMPOSITION object)

Headers
Content-Type: application/json
Body
{
  "message": "Error message",
  "validationErrors": [
    "error1",
    "error2"
  ]
}
Headers
Content-Type: application/json
If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
    "_type": "COMPOSITION",
    "name": {
        "_type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Responses404

404 Not Found is returned when an EHR with ehr_id does not exist or when a COMPOSITION with versioned_object_uid does not exist.

Headers
Content-Type: application/json
If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
    "_type": "COMPOSITION",
    "name": {
        "_type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}
Responses412

412 Precondition Failed is returned when If-Match request header doesn’t match the latest version (of this versioned object) on the service side. Returns also latest version_uid in the Location and ETag headers.

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

Update composition
PUT/ehr/{ehr_id}/composition/{versioned_object_uid}

Updates COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id. If the request body already contains a COMPOSITION.uid.value, it must match the versioned_object_uid in the URL. The existing latest version_uid of COMPOSITION resource (i.e the preceding_version_uid) must be specified in the If-Match header.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

versioned_object_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515

identifier of the COMPOSITION to be updated.

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

204 No Content is returned when COMPOSITION was deleted.

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

400 Bad Request is returned when the composition with preceding_version_uid is already deleted.

404 Not Found is returned when an EHR with ehr_id does not exist or when a COMPOSITION with preceding_version_uid does not exist.

409 Conflict is returned when supplied preceding_version_uid doesn’t match the latest version. Returns latest version in the Location and ETag headers.

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

Delete composition
DELETE/ehr/{ehr_id}/composition/{preceding_version_uid}

Deletes the COMPOSITION identified by preceding_version_uid and associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

preceding_version_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

identifier of the COMPOSITION to be deleted. This MUST be the last (most recent) version.

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

200 OK is returned when the COMPOSITION is successfully retrieved.

Headers
Content-Type: application/json
Body
{
    "name": {
        "_type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}

204 No Content is returned when the COMPOSITION is deleted (logically).

404 Not Found is returned when an EHR with ehr_id does not exist or when a COMPOSITION with version_uid does not exist.

Get composition by version id
GET/ehr/{ehr_id}/composition/{version_uid}

Retrieves a particular version of the COMPOSITION identified by version_uid and associated with the EHR identified by ehr_id.

See Resource identification for more details about the identifiers usage and meaning.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

version_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

VERSION identifier taken from VERSION.uid.value

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515?version_at_time=2015-01-20T19:30:22.765+01:00
Responses200204404

200 OK is returned when the COMPOSITION is successfully retrieved.

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
Body
{
    "_type": "COMPOSITION",
    "name": {
        "_type": "DV_TEXT",
        "value": "Vital Signs"
    },
    ...
}

204 No Content is returned when COMPOSITION with versioned_object_uid at specified version_at_time time has been deleted.

404 Not Found is returned when an EHR with ehr_id does not exist or when a VERSIONED_COMPOSITION with versioned_object_uid does not exist or when a COMPOSITION does not exists at version_at_time time.

Get composition at time
GET/ehr/{ehr_id}/composition/{versioned_object_uid}{?version_at_time}

Retrieves a version of the COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id. If version_at_time is supplied, retrieves the version extant at specified time, otherwise retrieves the latest COMPOSITION version.

Without the version_at_time parameter, this resource endpoint is similar to getting COMPOSITION by version id, but the format and semantics of the version_uid and the versioned_object_uid identifiers are different. The former is used to retrieve a specific known version of the COMPOSITION (e.g. one identified by 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1), whereas the later (e.g. an identifier like 8849182c-82ad-4088-a07f-48ead4180515) should be used to retrieve a version from the version container whenever the version_tree_id is unknown or irrelevant (such as when most recent version is requested).

See Resource identification for more details about the identifiers usage and meaning.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

versioned_object_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515

COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value

version_at_time
string (optional) Example: 2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format

VERSIONED_COMPOSITION

Management of VERSIONED_COMPOSITION resources.

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

200 OK is returned when the VERSIONED_COMPOSITION is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "_type": "VERSIONED_COMPOSITION",
  "uid": {
    "value": "8849182c-82ad-4088-a07f-48ead4180515"
  },
  "owner_id": {
    "id": {
      "_type": "HIER_OBJECT_ID",
      "value": "7d44b88c-4199-4bad-97dc-d78268e01398"
    },
    "namespace": "local",
    "type": "EHR"
  },
  "time_created": {
    "value": "2015-01-20T19:30:22.765+01:00"
  }
}

404 Not Found is returned when an EHR with ehr_id does not exist or when a VERSIONED_COMPOSITION with versioned_object_uid does not exist.

Get versioned composition
GET/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}

Retrieves a VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

versioned_object_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value

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

200 OK is returned when the VERSIONED_COMPOSITION revision history is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "_type": "REVISION_HISTORY",
  "items": [
    {
      "version_id": {
        "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
      },
      "audits": [
        {
          "system_id": "d60e2348-b083-48ce-93b9-916cef1d3a5a",
          "time_committed": {
            "value": "2015-01-20T19:30:22.765+01:00"
          },
          "change_type": {
            "value": "creation",
            "defining_code": {
              "terminology_id": {
                "value": "openehr"
              },
              "code_string": "249"
            }
          },
          "description": {
            "value": "An optional description string"
          },
          "committer": {
            "_type": "PARTY_IDENTIFIED",
            "name": "A user name"
          }
        }
      ]
    }
  ]
}

404 Not Found is returned when an EHR with ehr_id does not exist or when a VERSIONED_COMPOSITION with versioned_object_uid does not exist.

Get versioned composition revision history
GET/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/revision_history

Retrieves revision history of the VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

versioned_object_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value

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

200 OK is returned when the VERSION is successfully retrieved.

Headers
Content-Type: application/json
Body
{
    "_type": "ORIGINAL_VERSION",
    "contribution": {},
    "signature": "...",
    "commit_audit": {},
    "uid": "...",
    "data": {
        "_type": "COMPOSITION",
        "name": {
            "_type": "DV_TEXT",
            "value": "Vital Signs"
        }
        ...
    }
}

404 Not Found is returned when an EHR with ehr_id does not exist or when a VERSIONED_COMPOSITION with versioned_object_uid does not exist or when a VERSION with version_uid does not exist.

Get versioned composition version by id
GET/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}

Retrieves a VERSION identified by version_uid of a VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

versioned_object_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value

version_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

VERSION identifier taken from VERSION.uid.value

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/versioned_composition/8849182c-82ad-4088-a07f-48ead4180515/version?version_at_time=2015-01-20T19:30:22.765+01:00
Responses200404

200 OK is returned when the VERSION is successfully retrieved.

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/versioned_composition/8849182c-82ad-4088-a07f-48ead4180515/version/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
    "_type": "ORIGINAL_VERSION",
    "contribution": {},
    "signature": "...",
    "commit_audit": {},
    "uid": "...",
    "data": {
        "_type": "COMPOSITION",
        "name": {
            "_type": "DV_TEXT",
            "value": "Vital Signs"
        }
        ...
    }
}

404 Not Found is returned when an EHR with ehr_id does not exist or when a VERSIONED_COMPOSITION with versioned_object_uid does not exist or when a VERSION with version_uid does not exist.

Get versioned composition version at time
GET/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version{?version_at_time}

Retrieves a VERSION from the VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id. If version_at_time is supplied, retrieves the VERSION extant at specified time, otherwise retrieves the latest VERSION.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

versioned_object_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value

version_at_time
string (optional) Example: 2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format

DIRECTORY

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

Directory

Management of the directory FOLDER resource.

POST {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory
Requestsexample 1
Headers
Content-Type: application/json
Prefer: return={representation|minimal}
Body
{
    "items": [...],
    "folders": [{}]
}
Responses201400404

201 Created is returned when 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: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Body
{
    "uid": "...",
    "items": [...],
    "folders": [{}]
}

400 Bad Request is returned when the request has invalid ehr_id or invalid content (e.g. content could not be converted to a valid directory FOLDER)

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

Create directory
POST/ehr/{ehr_id}/directory

Creates a new directory FOLDER associated with the EHR identified by ehr_id.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

PUT {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory
Requestsexample 1
Headers
Content-Type: application/json
If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Prefer: return={representation|minimal}
Body
{
    "items": [...],
    "folders": [{}]
}
Responses200204400404412

200 OK is returned when directory is successfully updated and the updated resource is returned in the body when Prefer header value is return=representation.

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
Body
{
    "uid": "...",
    "items": [...],
    "folders": [{}]
}

204 No Content is returned when directory was updated and Prefer header is missing or is set to return=minimal.

Headers
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"

400 Bad Request is returned when the request has invalid ehr_id or invalid content (e.g. content could not be converted to a valid directory FOLDER)

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

412 Precondition Failed is returned when If-Match request header doesn’t match the latest version on the service side. Returns also latest version_uid in the Location and ETag headers.

Headers
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::3
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::3"

Update directory
PUT/ehr/{ehr_id}/directory

Updates directory FOLDER associated with the EHR identified by ehr_id. The existing latest version_uid of directory FOLDER resource (i.e the preceding_version_uid) must be specified in the If-Match header.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

DELETE {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory
Requestsexample 1
Headers
If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
Responses204400404412

204 No Content is returned when directory was deleted.

400 Bad Request is returned when the request has invalid ehr_id.

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

412 Precondition Failed is returned when If-Match request header doesn’t match the latest version on the service side. Returns also latest version_uid in the Location and ETag headers.

Headers
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::3
ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::3"

Delete directory
DELETE/ehr/{ehr_id}/directory

Deletes directory FOLDER associated with the EHR identified by ehr_id. The existing latest version_uid of directory FOLDER resource (i.e the preceding_version_uid) must be specified in the If-Match header.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1?path=episodes/a/b/c
Responses200404

200 OK is returned when the requested directory FOLDER is successfully retrieved.

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

404 Not Found is returned when an EHR with ehr_id does not exist or when a directory with version_uid does not exist or when path does not exists within the directory.

Get folder in directory version
GET/ehr/{ehr_id}/directory/{version_uid}{?path}

Retrieves a particular version of the directory FOLDER identified by version_uid and associated with the EHR identified by ehr_id. If path is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

version_uid
string (required) Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

VERSION identifier taken from VERSION.uid.value

path
string (optional) Example: episodes/a/b/c

A path to a sub-FOLDER; consists of slash-separated values of the name attribute of FOLDERs in the directory

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory?version_at_time=2015-01-20T19:30:22.765+01:00&path=episodes/a/b/c
Responses200204404

200 OK is returned when the requested directory FOLDER is successfully retrieved.

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

204 No Content is returned when directory at version_at_time time has been deleted.

404 Not Found is returned when an EHR with ehr_id does not exist or when a directory does not exists at version_at_time time or when path does not exists within the directory.

Get folder in directory version at time
GET/ehr/{ehr_id}/directory{?version_at_time,path}

Retrieves the version of the directory FOLDER associated with the EHR identified by ehr_id. If version_at_time is supplied, retrieves the version extant at specified time, otherwise retrieves the latest directory FOLDER version. If path is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

version_at_time
string (optional) Example: 2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format

path
string (optional) Example: episodes/a/b/c

A path to a sub-folder; consists of slash-separated values of the name attribute of FOLDERs in the directory

CONTRIBUTION

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

CONTRIBUTION

Management of CONTRIBUTION resources.

POST {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/contribution
Requestsexample 1
Headers
Content-Type: application/json
Prefer: return={representation|minimal}
Body
{
    "versions": [
        {
            "data": {
                /* optional JSON serialized COMPOSITION, FOLDER or EHR_STATUS object */
            },
            "preceding_version_uid": "<optional string>", 
            "signature": "<optional string>", 
            "lifecycle_state": 0,
            "commit_audit": {
                "change_type": {},
                "description": {},
                "committer": {
                    /* optional structure - will use the outer committer if absent */
                }
            }
        }
    ],
    "audit":{
        "committer":{
            "name": "<optional identifier of the committer>"  ,
            "external_ref":{
                "namespace": "demographic",
                "type": "PERSON",
                "id":{
                    "value": "<OBJECT_ID>"
                }
            }
        }
    }
}
Responses201400404

201 Created is returned when the CONTRIBUTION was created. Content body is only returned when Prefer header has return=representation otherwise only headers are returned.

Headers
Content-Type: application/json
Location: {baseUrl}/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/contribution/0826851c-c4c2-4d61-92b9-410fb8275ff0
ETag: "0826851c-c4c2-4d61-92b9-410fb8275ff0"
Body
{
  "_type": "CONTRIBUTION",
  "uid": {
    "value": "0826851c-c4c2-4d61-92b9-410fb8275ff0"
  },
  "versions": [
    {
      "_type": "OBJECT_REF",
      "id": {
        "_type": "OBJECT_VERSION_ID",
        "value": "fb458d9c-1323-42bc-b7f8-787f3660a0b5::91215053-854b-45b8-bb2a-3b0d255858d1::1"
      },
      "namespace": "local",
      "type": "COMPOSITION"
    },
    {
      "_type": "OBJECT_REF",
      "id": {
        "_type": "OBJECT_VERSION_ID",
        "value": "abcdefgh-1323-42bc-b7f8-787f3660a0ba::91215053-854b-45b8-bb2a-3b0d255858d1::1"
      },
      "namespace": "local",
      "type": "FOLDER"
    }
  ],
  "audit": {
    "system_id": "9624982A-9F42-41A5-9318-AE13D5F5031F",
    "committer": {
      "_type": "PARTY_IDENTIFIED",
      "name": "bna"
    },
    "time_committed": {
      "value": "2017-08-15T10:37:15.422+02:00"
    },
    "change_type": {
      "value": "creation",
      "defining_code": {
        "terminology_id": {
          "value": "openehr"
        },
        "code_string": "249"
      }
    },
    "description": {
      "value": "comment"
    }
  }
}

400 Bad Request is returned when the are validation errors in one of the attached locatables, modification type doesn’t match the operation - i.e. first version of a composition with MODIFICATION.

Body
{
  "message": "Error message",
  "validationErrors": [
    "error1",
    "...",
    "errorN"
  ]
}

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

Create contribution
POST/ehr/{ehr_id}/contribution

We will use the relaxed CONTRIBUTION XSD with the following attributes optional:

  • time_committed: server will always set it

  • UID: if provided will be accepted unless it is already used in which case an error will be returned

  • system_id: where provided will be validated

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/contribution/0826851c-c4c2-4d61-92b9-410fb8275ff0
Responses200404

200 OK is returned when the CONTRIBUTION is successfully retrieved.

Headers
Content-Type: application/json
Body
{
  "_type": "CONTRIBUTION",
  "uid": {
    "value": "0826851c-c4c2-4d61-92b9-410fb8275ff0"
  },
  "versions": [
    {
      "_type": "OBJECT_REF",
      "id": {
        "_type": "OBJECT_VERSION_ID",
        "value": "fb458d9c-1323-42bc-b7f8-787f3660a0b5::91215053-854b-45b8-bb2a-3b0d255858d1::1"
      },
      "namespace": "local",
      "type": "COMPOSITION"
    },
    {
      "_type": "OBJECT_REF",
      "id": {
        "_type": "OBJECT_VERSION_ID",
        "value": "abcdefgh-1323-42bc-b7f8-787f3660a0ba::91215053-854b-45b8-bb2a-3b0d255858d1::1"
      },
      "namespace": "local",
      "type": "FOLDER"
    }
  ],
  "audit": {
    "system_id": "9624982A-9F42-41A5-9318-AE13D5F5031F",
    "committer": {
      "_type": "PARTY_IDENTIFIED",
      "name": "bna"
    },
    "time_committed": {
      "value": "2017-08-15T10:37:15.422+02:00"
    },
    "change_type": {
      "value": "creation",
      "defining_code": {
        "terminology_id": {
          "value": "openehr"
        },
        "code_string": "249"
      }
    },
    "description": {
      "value": null
    }
  }
}

404 Not Found is returned when an EHR with ehr_id does not exist or when a CONTRIBUTION with contribution_uid does not exist.

Get contribution by id
GET/ehr/{ehr_id}/contribution/{contribution_uid}

URI Parameters
HideShow
ehr_id
string (required) Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value

contribution_uid
string (required) Example: 0826851c-c4c2-4d61-92b9-410fb8275ff0

CONTRIBUTION uid

Generated with aglio on 24 Apr 2021