API docs by Redocly

Demographic API (development)

Specifications Editorial Committee openEHR: info@openehr.org URL: https://specifications.openehr.org/ License: Creative Commons Attribution-NoDerivs 3.0 Unported

Description

Purpose

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

Prerequisite documents for reading this document include:

Related documents include:

Status

This specification is in the DEVELOPMENT 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/demographic.html.

AGENT

Management of the AGENT class.

Create AGENT

Creates the first version of a new AGENT.

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

_type
string
Value: "AGENT"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "AGENT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "AGENT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Get AGENT

Retrieves a version of the AGENT identified by uid_based_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 AGENT (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 AGENT version.

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

path Parameters
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
{
  • "_type": "AGENT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Update AGENT

Updates AGENT identified by uid_based_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 AGENT.uid.value, it must match the uid_based_id in the URL.

The existing latest version_uid of AGENT resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
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 AGENT.

_type
string
Value: "AGENT"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "AGENT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "AGENT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Delete AGENT

Deletes the AGENT identified by uid_based_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
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

GROUP

Management of the GROUP class.

Create GROUP

Creates the first version of a new GROUP.

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

_type
string
Value: "GROUP"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "GROUP",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "GROUP",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Get GROUP

Retrieves a version of the GROUP identified by uid_based_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 GROUP (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 GROUP version.

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

path Parameters
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
{
  • "_type": "GROUP",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Update GROUP

Updates GROUP identified by uid_based_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 GROUP.uid.value, it must match the uid_based_id in the URL.

The existing latest version_uid of GROUP resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
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 GROUP.

_type
string
Value: "GROUP"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "GROUP",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "GROUP",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Delete GROUP

Deletes the GROUP identified by uid_based_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
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

ORGANISATION

Management of the ORGANISATION class.

Create ORGANISATION

Creates the first version of a new ORGANISATION.

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

_type
string
Value: "ORGANISATION"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "ORGANISATION",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "ORGANISATION",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Get ORGANISATION

Retrieves a version of the ORGANISATION identified by uid_based_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 ORGANISATION (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 ORGANISATION version.

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

path Parameters
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
{
  • "_type": "ORGANISATION",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Update ORGANISATION

Updates ORGANISATION identified by uid_based_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 ORGANISATION.uid.value, it must match the uid_based_id in the URL.

The existing latest version_uid of ORGANISATION resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
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 ORGANISATION.

_type
string
Value: "ORGANISATION"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "ORGANISATION",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "ORGANISATION",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Delete ORGANISATION

Deletes the ORGANISATION identified by uid_based_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
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

PERSON

Management of the PERSON class.

Create PERSON

Creates the first version of a new PERSON.

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

_type
string
Value: "PERSON"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "PERSON",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "PERSON",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Get PERSON

Retrieves a version of the PERSON identified by uid_based_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 PERSON (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 PERSON version.

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

path Parameters
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
{
  • "_type": "PERSON",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Update PERSON

Updates PERSON identified by uid_based_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 PERSON.uid.value, it must match the uid_based_id in the URL.

The existing latest version_uid of PERSON resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
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 PERSON.

_type
string
Value: "PERSON"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

Array of objects (DV_TEXT)
Array of objects (PARTY_REF)

Responses

Request samples

Content type
application/json
{
  • "_type": "PERSON",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "PERSON",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "languages": [
    ],
  • "roles": [
    ]
}

Delete PERSON

Deletes the PERSON identified by uid_based_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
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

ROLE

Management of the ROLE class.

Create ROLE

Creates the first version of a new ROLE.

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

_type
string
Value: "ROLE"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

object (DV_INTERVAL_of_DATE)
required
object (PARTY_REF)

Identifier for parties in a demographic or identity service.

capabilities
Array of objects (CAPABILITY)

See CAPABILITY schema details.

Responses

Request samples

Content type
application/json
{
  • "_type": "ROLE",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "time_validity": {
    },
  • "performer": {
    },
  • "capabilities": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "ROLE",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "time_validity": {
    },
  • "performer": {
    },
  • "capabilities": [
    ]
}

Get ROLE

Retrieves a version of the ROLE identified by uid_based_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 ROLE (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 ROLE version.

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

path Parameters
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
{
  • "_type": "ROLE",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "time_validity": {
    },
  • "performer": {
    },
  • "capabilities": [
    ]
}

Update ROLE

Updates ROLE identified by uid_based_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 ROLE.uid.value, it must match the uid_based_id in the URL.

The existing latest version_uid of ROLE resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
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 ROLE.

_type
string
Value: "ROLE"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
identities
required
Array of objects (PARTY_IDENTITY)

See PARTY_IDENTITY schema details.

contacts
Array of objects (CONTACT)

See CONTACT schema details.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

relationships
Array of objects (PARTY_RELATIONSHIP)

See PARTY_RELATIONSHIP schema details.

object (DV_INTERVAL_of_DATE)
required
object (PARTY_REF)

Identifier for parties in a demographic or identity service.

capabilities
Array of objects (CAPABILITY)

See CAPABILITY schema details.

Responses

Request samples

Content type
application/json
{
  • "_type": "ROLE",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "time_validity": {
    },
  • "performer": {
    },
  • "capabilities": [
    ]
}

Response samples

Content type
application/json
{
  • "_type": "ROLE",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "identities": [
    ],
  • "contacts": [
    ],
  • "details": { },
  • "relationships": [
    ],
  • "time_validity": {
    },
  • "performer": {
    },
  • "capabilities": [
    ]
}

Delete ROLE

Deletes the ROLE identified by uid_based_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
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

VERSIONED_PARTY

Management of the VERSIONED_PARTY class.

Get VERSIONED_PARTY

Retrieves a VERSIONED_PARTY identified by versioned_object_uid.

path Parameters
versioned_object_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b

VERSIONED_PARTY identifier taken from VERSIONED_PARTY.uid.value.

Responses

Response samples

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

Get VERSIONED_PARTY revision history

Retrieves revision history of the VERSIONED_PARTY identified by versioned_object_uid.

path Parameters
versioned_object_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b

VERSIONED_PARTY identifier taken from VERSIONED_PARTY.uid.value.

Responses

Response samples

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

Get VERSIONED_PARTY version at time

Retrieves a VERSION from the VERSIONED_PARTY identified by versioned_object_uid.

If version_at_time is supplied, retrieves the VERSION extant at specified time, otherwise retrieves the latest VERSION.

path Parameters
versioned_object_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b

VERSIONED_PARTY identifier taken from VERSIONED_PARTY.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_PARTY version by id

Retrieves a VERSION identified by version_uid of a VERSIONED_PARTY identified by versioned_object_uid.

path Parameters
versioned_object_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b

VERSIONED_PARTY identifier taken from VERSIONED_PARTY.uid.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": [
    ]
}

CONTRIBUTION

Management of CONTRIBUTION class.

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

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

The CONTRIBUTION uid.

Responses

Response samples

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

CAPABILITY

The CAPABILITY schema, formally specified in the Reference Model as the CAPABILITY class:

_type
string
Value: "CAPABILITY"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
credentials
required
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

object (DV_INTERVAL_of_DATE)
{
  • "_type": "CAPABILITY",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "credentials": { },
  • "time_validity": {
    }
}

CONTACT

The CONTACT schema, formally specified in the Reference Model as the CONTACT class:

_type
string
Value: "CONTACT"
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
Array of objects (ADDRESS)
object (DV_INTERVAL_of_DATE)
{
  • "_type": "CONTACT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "addresses": [
    ],
  • "time_validity": {
    }
}

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": {
    }
}

PARTY_IDENTITY

The PARTY_IDENTITY schema, formally specified in the Reference Model as the PARTY_IDENTITY 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)
details
required
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

{
  • "_type": "string",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "details": { }
}

PARTY_RELATIONSHIP

The PARTY_RELATIONSHIP resource, formally specified in the Reference Model as the PARTY_RELATIONSHIP 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 (PARTY_REF)

Identifier for parties in a demographic or identity service.

required
object (PARTY_REF)

Identifier for parties in a demographic or identity service.

details
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

object (DV_INTERVAL_of_DATE)
{
  • "_type": "string",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "source": {
    },
  • "target": {
    },
  • "details": { },
  • "time_validity": {
    }
}