EHR API (latest)

Description

Purpose

This specification describes service endpoints, resources and operations as well as details of requests and responses that interacts with EHR openEHR API in a RESTful manner.

Prerequisite documents for reading this document include:

Related documents include:

Status

This specification is in the STABLE state, and can be downloaded as OpenAPI specification file (in YAML format) for validation, or for code generators. Users are encouraged to comment on and/or advise on these paragraphs as well as the main content.

The development version of this document can be found at https://specifications.openehr.org/releases/ITS-REST/development/ehr.html.

EHR

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

Create 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.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
optional

An EHR_STATUS resource MAY be also supplied by the client as the request body.

_type
string
Value: "EHR_STATUS"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (PARTY_PROXY)
is_queryable
required
boolean
Default: true
is_modifiable
required
boolean
Default: true
other_details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

Get EHR by subject id

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.

query Parameters
subject_id
required
string
Example: subject_id=ins01

The EHR subject id.

subject_namespace
required
string
Example: subject_namespace=examples

The EHR subject id namespace.

Responses

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

Create EHR with 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
optional

An EHR_STATUS resource MAY be also supplied by the client as the request body.

_type
string
Value: "EHR_STATUS"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (PARTY_PROXY)
is_queryable
required
boolean
Default: true
is_modifiable
required
boolean
Default: true
other_details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

Get EHR by id

Retrieve the EHR with the specified ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

Responses

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

EHR_STATUS

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

Get EHR_STATUS by version id

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

version_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2

VERSION identifier taken from VERSION.uid.value.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Get EHR_STATUS 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Update 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
required

The new EHR_STATUS.

_type
string
Value: "EHR_STATUS"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (PARTY_PROXY)
is_queryable
required
boolean
Default: true
is_modifiable
required
boolean
Default: true
other_details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Get versioned EHR_STATUS

Retrieves a VERSIONED_EHR_STATUS associated with an EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

Responses

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "owner_id": {
    },
  • "time_created": {
    }
}

Get versioned EHR_STATUS revision history

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get versioned EHR_STATUS 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

Get versioned EHR_STATUS version by id

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

version_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2

VERSION identifier taken from VERSION.uid.value.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

COMPOSITION

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

Create COMPOSITION

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
required

The COMPOSITION.

_type
string
Value: "COMPOSITION"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (CODE_PHRASE)
required
object (CODE_PHRASE)
required
object (DV_CODED_TEXT)
required
object (EVENT_CONTEXT)
required
object (PARTY_PROXY)
content
required
Array of objects (CONTENT_ITEM)

See CONTENT_ITEM schema details.

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Get COMPOSITION

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

The uid_based_id can take a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a version_uid), or a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid). 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) is 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).

When the uid_based_id has the form of a HIER_OBJECT_ID, if the version_at_time is supplied, retrieves the version extant at specified time, otherwise retrieves the latest COMPOSITION version.

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

An abstract identifier: it can take a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a version_uid), or a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid).

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Update COMPOSITION

Updates COMPOSITION identified by uid_based_id and associated with the EHR identified by ehr_id.

The uid_based_id can take only a form of an HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid).

If the request body already contains a COMPOSITION.uid.value, it must match the uid_based_id 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

uid_based_id
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515

An identifier in a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid).

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
required

The new COMPOSITION.

_type
string
Value: "COMPOSITION"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (CODE_PHRASE)
required
object (CODE_PHRASE)
required
object (DV_CODED_TEXT)
required
object (EVENT_CONTEXT)
required
object (PARTY_PROXY)
content
required
Array of objects (CONTENT_ITEM)

See CONTENT_ITEM schema details.

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Delete COMPOSITION

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

The uid_based_id MUST be in a form of an OBJECT_VERSION_ID identifier taken from the last (most recent) VERSION.uid.value, representing the preceding_version_uid to be deleted.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

An identifier in a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a version_uid).

Responses

Get versioned COMPOSITION

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

Responses

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "owner_id": {
    },
  • "time_created": {
    }
}

Get versioned COMPOSITION revision history

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get versioned COMPOSITION 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

Get versioned COMPOSITION version by id

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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

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

VERSION identifier taken from VERSION.uid.value.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

DIRECTORY

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

Create directory

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

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
required

The directory.

_type
string
Value: "FOLDER"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
Array of objects (OBJECT_REF)
folders
Array of objects (FOLDER)
details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Update 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
required

The new directory.

_type
string
Value: "FOLDER"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
Array of objects (OBJECT_REF)
folders
Array of objects (FOLDER)
details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Delete 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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Responses

Response samples

Content type
application/json
{
  • "message": "Error message",
  • "validationErrors": [
    ]
}

Get folder in directory version at time

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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

path
string
Example: path=episodes/a/b/c

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

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Get folder in directory version

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.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

version_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2

VERSION identifier taken from VERSION.uid.value.

query Parameters
path
string
Example: path=episodes/a/b/c

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

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

CONTRIBUTION

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

Create CONTRIBUTION

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

  • uid: when provided, it will be accepted in case is not in-use, otherwise error will be returned
  • audit.time_committed: server will always set it
  • audit.system_id: when provided, it will be validated
path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json
required

The CONTRIBUTION.

object (HIER_OBJECT_ID)
required
Array of objects (UPDATE_VERSION)
required
object (UPDATE_AUDIT)

The set of attributes required to document the committal of an information item to a repository. Used by the server to create an AUDIT_DETAILS object.

Responses

Request samples

Content type
application/json
{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}

Get CONTRIBUTION by id

Retrieves a CONTRIBUTION identified by contribution_uid and associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

The CONTRIBUTION uid.

Responses

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}

CONTENT_ITEM

The abstract CONTENT_ITEM class:

_type
required
string
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (CODE_PHRASE)
required
object (CODE_PHRASE)
Array of objects (PARTICIPATION)
object (OBJECT_REF)
required
object (PARTY_PROXY)
object (PARTY_PROXY)
data
required
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

Example
{
  • "_type": "ADMIN_ENTRY",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "language": {
    },
  • "encoding": {
    },
  • "other_participations": [
    ],
  • "workflow_id": {
    },
  • "subject": {
    },
  • "provider": {
    },
  • "data": { }
}

ITEM

The abstract ITEM class:

_type
string
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
object (DV_CODED_TEXT)
object (DATA_VALUE)
object (DV_TEXT)
Example
{
  • "_type": "ELEMENT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "null_flavour": {
    },
  • "value": {
    },
  • "null_reason": {
    }
}

ITEM_STRUCTURE

The abstract ITEM_STRUCTURE class:

_type
string
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (ELEMENT)
Example
{
  • "_type": "ITEM_SINGLE",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "item": {
    }
}