Gateway HTTP REST API

ACCESS

Set user access to the document

POST /access/document

Description:

Sets access to the document with the specified CID for the user with the userID. Possible access levels: owner, admin, read, noAccess

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Request	body	DTO with data to create group access	Yes	model.DocAccessSetRequest
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description
200	Indicates that the request to change the level of access to the document was successfully created
400	Is returned when the request has invalid content.
404	Is returned when the userID for which access is set is not found
500	Is returned when an unexpected error occurs while processing a request

Get a document access list

GET /access/document/

Description:

Returns the list of documents available to the user

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.DocAccessListResponse
400	Is returned when the request has invalid content.
500	Is returned when an unexpected error occurs while processing a request

DEFINITION

Get list stored queries

GET /definition/query/{qualified_query_name}

Description:

Retrieves list of all stored queries on the system matched by qualified_query_name as pattern.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	Yes	string
qualified_query_name	path	If pattern should given be in the format of [{namespace}::]{query-name}, and when is empty, it will be treated as	No	string

Responses

Code	Description	Schema
200	OK	[ model.StoredQuery ]
500	Is returned when an unexpected error occurs while processing a request

Store a query

PUT /definition/query/{qualified_query_name}

Description:

Stores a new query, or updates an existing query on the system

Parameters

Name	Located in	Description	Required	Schema
qualified_query_name	path	If pattern should given be in the format of [{namespace}::]{query-name}, and when is empty, it will be treated as	Yes	string
query_type	query	Parameter indicating the query language/type	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	Yes	string

Responses

Code	Description
200	Is returned when the query was successfully stored.
400	Is returned when the server was unable to store the query. This could be due to incorrect request body (could not be parsed, etc), unknown query type, etc.
500	Is returned when an unexpected error occurs while processing a request

Store a query by version

PUT​ /definition​/query​/{qualified_query_name}​/{version}

Description:

Stores a query, at a specified version, on the system.

Parameters

Name	Located in	Description	Required	Schema
qualified_query_name	path	If pattern should given be in the format of [{namespace}::]{query-name}, and when is empty, it will be treated as	Yes	string
version	path	A SEMVER version number. This can be a an exact version (e.g. 1.7.1), or a pattern as partial prefix, in a form of {major} or {major}.{minor} (e.g. 1 or 1.0), in which case the highest (latest) version matching the prefix will be considered	Yes	string
query_type	query	Parameter indicating the query language/type	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string

Responses

Code	Description
200	Is returned when the query was successfully stored
400	Is returned when the server was unable to store the query. This could be due to incorrect request body (could not be parsed, etc), unknown query type, etc
409	Is returned when a query with the given 'qualifiedqueryname' and 'version' already exists on the server
500	Is returned when an unexpected error occurs while processing a request

Get stored query by version

GET /definition/query/{qualified_query_name}/{version}

Description:

Retrieves the definition of a particular stored query (at specified version) and its associated metadata.

Parameters

Name	Located in	Description	Required	Schema
qualified_query_name	path	If pattern should given be in the format of [{namespace}::]{query-name}, and when is empty, it will be treated as	No	string
version	path	A SEMVER version number. This can be a an exact version (e.g. 1.7.1), or a pattern as partial prefix, in a form of {major} or {major}.{minor} (e.g. 1 or 1.0), in which case the highest (latest) version matching the prefix will be considered.	No	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	Yes	string

Responses

Code	Description	Schema
200	OK	model.StoredQuery
400	Is returned when the request has invalid content.
404	Is returned when a stored query with {qualifiedqueryname} and {version} does not exist.
500	Is returned when an unexpected error occurs while processing a request

Get a list of templates

GET /definition/template/adl1.4

Description:

List the available ADL 1.4 operational templates (OPT) on the system.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string

Responses

Code	Description	Schema
200	OK	[ model.Template ]
400	Is returned because of invalid content.
500	Is returned when an unexpected error occurs while processing a request

Store a template

POST /definition/template/adl1.4

Description:

Upload a new ADL 1.4 operational template (OPT).

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Prefer	header	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.	Yes	string

Responses

Code	Description	Schema
201	Is returned when the query was successfully uploaded.	model.Template
400	Is returned when unable to upload a template, because of invalid content.
409	Is returned when a template with same {template_id} (at given version, if supplied) already exists.
500	Is returned when an unexpected error occurs while processing a request

Get a template

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

Description:

Retrieves the ADL 1.4 operational template (OPT) identified by {templateid} identifier.

Parameters

Name	Located in	Description	Required	Schema
template_id	path	Template identifier. Example: Vital Signs	No	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	string
400	Is returned when the request has invalid content.
404	Is returned when a stored query with {qualifiedqueryname} and {version} does not exist.
406	Is returned when template with certain ID created with other accept header
500	Is returned when an unexpected error occurs while processing a request

EHR

Get EHR summary by subject id

GET /ehr{?subject_id,subject_namespace}

Description:

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.

Parameters

Name	Located in	Description	Required	Schema
subject_id	query	subject id. Example: ins01	Yes	string
subject_namespace	query	id namespace. Example: examples	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.EhrSummary
202	Is returned when the request is still being processed
400	Is returned when userID is empty
404	Is returned when an EHR with ehr_id does not exist.

Create EHR

POST /ehr

Description:

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.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
GroupAccessId	header	GroupAccessId - UUID. If not specified, the default access group will be used.	No	string
Prefer	header	The new EHR resource is returned in the body when the request’s Prefer header value is return=representation, otherwise only headers are returned.	Yes	string
Request	body	Query Request	Yes	model.EhrCreateRequest

Responses

Code	Description	Schema
201	Created	model.EhrSummary
400	Is returned when the request body (if provided) could not be parsed.
409	Unable to create a new EHR due to a conflict with an already existing EHR with the same subject id, namespace pair.
500	Is returned when an unexpected error occurs while processing a request

Get EHR summary by id

GET /ehr/{ehr_id}

Description:

Retrieve the EHR with the specified ehr_id

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.EhrSummary
202	Is returned when the request is still being processed
400	Is returned when userID is empty
404	Is returned when an EHR with ehr_id does not exist.
500	Is returned when an unexpected error occurs while processing a request

Create EHR with id

PUT /ehr/{ehr_id}

Description:

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.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
Prefer	header	The new EHR resource is returned in the body when the request’s Prefer header value is return=representation, otherwise only headers are returned.	Yes	string
ehr_id	path	An UUID as a user specified EHR identifier. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
Request	body	Query Request	Yes	model.EhrCreateRequest

Responses

Code	Description	Schema
201	Created	model.EhrSummary
400	Is returned when the request body (if provided) could not be parsed.
409	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.
500	Is returned when an unexpected error occurs while processing a request

COMPOSITION

Get all COMPOSITIONs

GET /ehr/{ehr_id}/composition

Description:

Retrieves all versions of all COMPOSITIONs associated with the EHR identified by ehr_id.

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	[ model.EhrDocumentItem]
400	Is returned when AuthUserId or EhrSystemId is not specified
404	is returned when an EHR with ehr_id does not exist.
500	Is returned when an unexpected error occurs while processing a request

Create COMPOSITION

POST /ehr/{ehr_id}/composition

Description:

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

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
GroupAccessId	header	GroupAccessId - UUID. If not specified, the default access group will be used.	No	string
Prefer	header	The new EHR resource is returned in the body when the request’s Prefer header value is return=representation, otherwise only headers are returned.	Yes	string
Request	body	COMPOSITION	Yes	model.Composition

Responses

Code	Description	Schema
201	Created	model.Composition
400	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	Is returned when an EHR with ehr_id does not exist.
422	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).
500	Is returned when an unexpected error occurs while processing a request

Delete COMPOSITION

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

Description:

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

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
preceding_version_uid	path	Identifier of the COMPOSITION to be deleted. This MUST be the last (most recent) version. Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description
204	No Content is returned when COMPOSITION was deleted.
400	Bad Request is returned when the composition with preceding_version_uid is already deleted.
404	Not Found is returned when an EHR with ehrid does not exist or when a COMPOSITION with precedingversion_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.
500	Is returned when an unexpected error occurs while processing a request

Get COMPOSITION by version id

GET /ehr/{ehr_id}/composition/{version_uid}

Description:

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

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
version_uid	path	VERSION identifier taken from VERSION.uid.value. Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.Composition
202	Is returned when the request is still being processed
204	Is returned when the COMPOSITION is deleted (logically).
400	Is returned when AuthUserId is not specified
404	is returned when an EHR with ehr_id does not exist or when an COMPOSITION with version_uid does not exist.
500	Is returned when an unexpected error occurs while processing a request

Update COMPOSITION

PUT /ehr/{ehrid}/composition/{versioned_object_uid}

Description:

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.

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
versioned_object_uid	path	identifier of the COMPOSITION to be updated. Example: 8849182c-82ad-4088-a07f-48ead4180515	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
Prefer	header	The updated COMPOSITION resource is returned to the body when the request’s Prefer header value is return=representation, otherwise only headers are returned.	Yes	string
If-Match	header	The existing latest versionuid of COMPOSITION resource (i.e the precedingversion_uid). Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1	Yes	string
Request	body	List of changes in COMPOSITION	Yes	model.Composition

Responses

Code	Description	Schema
200	Is returned when the COMPOSITION is successfully updated and the updated resource is returned in the body when Prefer header value is return=representation.	model.Composition
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)
404	Not Found is returned when an EHR with ehrid does not exist or when a COMPOSITION with versionobject_uid does not exist.
412	Version conflict 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 ETagheaders.
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).
500	Is returned when an unexpected error occurs while processing a request

DIRECTORY

Delete DIRECTOTY

DELETE /ehr/{ehr_id}/directory

Summary:

Delete DIRECTORY folder associated with the EHR identified by ehr_id.

Description:

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

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Prefer	header	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.	Yes	string
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
patient_id	query	Patient UserId	Yes	string

Responses

Code	Description
204	Is returned when the resource identified by the request parameters has been (logically) deleted
400	Is returned when the request has invalid content
404	Is returned when an EHR with {ehr_id} does not exist, or DIRECTORY with that version is not exist
409	Is returned when a resource with same identifier(s) already exists, or previous request still in progress
412	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
500	Is returned when an unexpected error occurs while processing a request

Get folder in directory version at time

GET /ehr/{ehr_id}/directory{?version_at_time,path}

Description:

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.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Prefer	header	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.	Yes	string
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
version_at_time	query	Example: version_at_time=2015-01-20T19:30:22.765+01:00 A given time in the extended ISO 8601 format	Yes	string
path	query	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	Yes	string
patient_id	query	Patient UserId	Yes	string

Responses

Code	Description	Schema
200	Is returned when the FOLDER is successfully retrieved	model.Directory
204	Is returned when the resource identified by the request parameters (at specified {versionattime}) time has been deleted
400	Is returned when the request has invalid content
404	Is returned when an EHR with {ehrid} does not exist, or when a directory does not exist at the specified {versionat_time}, or when {path} does not exists within the directory
500	Is returned when an unexpected error occurs while processing a request

Create DIRECTORY

POST /ehr/{ehr_id}/directory

Description:

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

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	Doctor UserId	Yes	string
Prefer	header	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.	Yes	string
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
patient_id	query	Patient UserId	Yes	string

Responses

Code	Description	Schema
201	Is returned when the DIRECTORY was successfully created.	model.Directory
400	Is returned when the request has invalid content
404	Is returned when an EHR with {ehr_id} does not exist
409	Is returned when a resource with same identifier(s) already exists, or previous request still in progress
500	Is returned when an unexpected error occurs while processing a request

Update DIRECTORY

PUT /ehr/{ehr_id}/directory

Description:

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.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Prefer	header	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.	Yes	string
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
patient_id	query	Patient UserId	Yes	string

Responses

Code	Description	Schema
200	Is returned when the DIRECTORY was successfully updated	model.Directory
204	Is returned when directory was updated and 'Prefer' header is missing or is set to 'return=minimal'
400	Is returned when the request has invalid content
404	Is returned when an EHR with {ehr_id} does not exist, or DIRECTORY with that version is not exist
409	Is returned when a resource with same identifier(s) already exists, or previous request still in progress
412	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
500	Is returned when an unexpected error occurs while processing a request

Get folder in DIRECTORY by version

GET /ehr/{ehr_id}/directory/{version_uid}{?path}

Description:

https://specifications.openehr.org/releases/ITS-REST/latest/ehr.html#tag/DIRECTORY/operation/directorygetattime 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.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Prefer	header	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.	Yes	string
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
version_uid	query	Example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2 VERSION identifier taken from VERSION.uid.value	Yes	string
path	query	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	Yes	string
patient_id	query	Patient UserId	Yes	string

Responses

Code	Description	Schema
200	Is returned when the FOLDER is successfully retrieved	model.Directory
204	Is returned when the resource identified by the request parameters (at specified {version_at_time}) time has been deleted
400	Is returned when the request has invalid content
404	Is returned when an EHR with {ehr_id} does not exist, or when a directory does not exist at the specified {versionat_time}, or when {path} does not exists within the directory
500	Is returned when an unexpected error occurs while processing a request

EHR_STATUS

Get EHR_STATUS version by time

GET /ehr/{ehr_id}/ehr_status{?version_at_time}

Description:

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.

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
version_at_time	query	A given time in the extended ISO 8601 format. Example: 2015-01-20T19:30:22.765+01:00	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.EhrStatusUpdate
202	Is returned when the request is still being processed
400	Is returned when the request has invalid content such as an invalid version_at_time format.
404	Is 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
500	Is returned when an unexpected error occurs while processing a request

Update EHR_STATUS

PUT /ehr/{ehr_id}/ehr_status

Description:

Updates EHR_STATUS associated with the EHR identified by ehr_id.

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
If-Match	header	The existing latest version_uidof EHR_STATUS resource (i.e. the preceding_version_uid) must be specified.	Yes	string
Prefer	header	Updated resource is returned in the body when the request’s Preferheader value is return=representation, otherwise only headers are returned.	Yes	string
Request	body	EHR_STATUS	Yes	model.EhrStatusUpdate

Responses

Code	Description	Schema
200	OK	model.EhrStatusUpdate
204	Is returned when Prefer header is missing or is set to return=minimal
400	Is returned when the request has invalid content.
404	Is returned when an EHR with ehr_id does not exist.
412	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.
500	Is returned when an unexpected error occurs while processing a request

Get EHR_STATUS by version id

GET /ehr/{ehr_id}/ehr_status/{version_uid}

Description:

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

Parameters

Name	Located in	Description	Required	Schema
ehr_id	path	EHR identifier taken from EHR.ehr_id.value. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
version_uid	path	VERSION identifier taken from VERSION.uid.value. Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.EhrStatusUpdate
202	Is returned when the request is still being processed
400	Is returned when AuthUserId is not specified
404	is returned when an EHR with ehr_id does not exist or when an EHR_STATUS with version_uid does not exist.
500	Is returned when an unexpected error occurs while processing a request

QUERY

Execute stored AQL (GET)

GET /query/{qualified_query_name}

Description:

Execute a stored query, identified by the supplied qualified_query_name (at latest version), fetching fetch numbers of rows from offset and passing query_parameters to the underlying query engine. See also details on usage of query parameters. Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
qualified_query_name	path	If pattern should given be in the format of [{namespace}::]{query-name}, and when is empty, it will be treated as	Yes	string
ehr_id	query	An optional parameter to execute the query within an EHR context.	No	string
offset	query	The row number in result-set to start result-set from (0-based), default is 0.	No	string
fetch	query	Number of rows to fetch (the default depends on the implementation).	No	string

Responses

Code	Description	Schema
200	OK	model.QueryResponse
400	Is returned when the server was unable to execute the query due to invalid input, e.g. a required parameter is missing, or at least one of the parameters has invalid syntax
404	Is returned when a stored query with qualifiedqueryname does not exists.
408	Is returned when there is a query execution timeout

Execute stored AQL (POST)

POST /query/{qualified_query_name}

Description:

Execute a stored query, identified by the supplied {qualified_query_name} (at latest version). See also details on usage of query parameters. Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
qualified_query_name	path	If pattern should given be in the format of [{namespace}::]{query-name}, and when is empty, it will be treated as	Yes	string
Request	body	Query Request	Yes	model.QueryRequest

Responses

Code	Description	Schema
200	OK	model.QueryResponse
400	Is returned when the server was unable to execute the query due to invalid input, e.g. a required parameter is missing, or at least one of the parameters has invalid syntax
404	Is returned when a stored query with qualifiedqueryname does not exists.
408	Is returned when there is a query execution timeout

Execute ad-hoc AQL query

GET /query/aql

Description:

Execute a given ad-hoc AQL query, supplied by {q} parameter, fetching {fetch} numbers of rows from {offset} and passing {query_parameters} to the underlying query engine. See also details on usage of query parameters.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Request	body	Query Request	Yes	model.QueryRequest
ehr_id	query	An optional parameter to execute the query within an EHR context.	No	string
q	query	AQL. Example: {q=SELECT e/ehrid/value, c/context/starttime/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.bloodpressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolicbp} The AQL query to be executed.	No	string
offset	query	The row number in result-set to start result-set from (0-based), default is 0.	No	string
fetch	query	Number of rows to fetch (the default depends on the implementation).	No	string

Responses

Code	Description	Schema
200	OK	model.QueryResponse
400	Is returned when the server was unable to execute the query due to invalid input, e.g. a request with missing q parameter or an invalid query syntax.
408	Is returned when there is a query execution timeout (i.e. maximum query execution time reached, therefore the server aborted the execution of the query).
500	Is returned when an unexpected error occurs while processing a request

Execute ad-hoc (non-stored) AQL query

POST /query/aql

Description:

Execute ad-hoc query, supplied by q attribute, fetching {fetch} numbers of rows from {offset} and passing {query_parameters} to the underlying query engine. See also details on usage of query parameters.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Request	body	Query Request	Yes	model.QueryRequest

Responses

Code	Description	Schema
200	OK	model.QueryResponse
400	Is returned when the server was unable to execute the query due to invalid input, e.g. a request with missing q parameter or an invalid query syntax.
408	Is returned when there is a query execution timeout (i.e. maximum query execution time reached, therefore the server aborted the execution of the query).
500	Is returned when an unexpected error occurs while processing a request

REQUEST

Get list of transactions requests by authorized user

GET /requests/

Description:

Returning only transactions which in progress

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
limit	query	default: 10	Yes	string
offset	query	id namespace. Example: examples	Yes	string

Responses

Code	Description	Schema
200	OK	processing.RequestsResult
400	Is returned when userID is empty
404	Is returned when requests not exist
500	Is returned when an unexpected error occurs while processing a request

Get list of transactions by request_id

GET /requests/{request_id}

Description:

Returning only transactions which in progress

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
request_id	path	Unique id of request	Yes	string

Responses

Code	Description	Schema
200	OK	processing.RequestResult
400	Is returned when userID or request_id is empty
404	Is returned when requests not exist
500	Is returned when an unexpected error occurs while processing a request

USER

Register user

POST /user/register

Parameters

Name	Located in	Description	Required	Schema
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
Request	body	User creation request. role: 0 - Patient, 1 - Doctor. Fields Name, Address, Description, PictureURL are required for Doctor role	Yes	model.UserCreateRequest

Responses

Code	Description
201	Indicates that the request has succeeded and transaction about register new user has been created
400	The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
409	User with that userID already exist
422	Password, systemID or role incorrect
500	Is returned when an unexpected error occurs while processing a request

Get user info

GET /user/{user_id}

Description:

Get information about the user by user_id

Parameters

Name	Located in	Description	Required	Schema
user_id	path	The identifier of the requested user info	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.UserInfo
400	user_id is incorrect or requested user is not a doctor
404	User with ID not exist
500	Is returned when an unexpected error occurs while processing a request

Get doctor info by code

GET /user/code/{code}

Description:

Get information about the doctor by code

Parameters

Name	Located in	Description	Required	Schema
code	path	The pin code of the requested doctor	Yes	string

Responses

Code	Description	Schema
200	OK	model.UserInfo
400	code is incorrect or requested user is not a doctor
404	User code is not exist
500	Is returned when an unexpected error occurs while processing a request

User group create

POST /user/group

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
Request	body	User group	Yes	model.UserGroup

Responses

Code	Description	Schema
201	Indicates that the request has succeeded and transaction about create new user group has been created	model.UserGroup
400	The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
404	User with ID not exist
409	Group with that Name already exist
500	Is returned when an unexpected error occurs while processing a request

Get a list of user groups

GET /user/group

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.UserGroup
400	The request could not be understood by the server due to incorrect syntax.
404	Is returned when groupID does not exist
500	Is returned when an unexpected error occurs while processing a request

Get user group by ID

GET /user/group/{group_id}

Parameters

Name	Located in	Description	Required	Schema
group_id	path	User group identifier. Example: 7d44b88c-4199-4bad-97dc-d78268e01398	Yes	string
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string

Responses

Code	Description	Schema
200	OK	model.UserGroup
400	The request could not be understood by the server due to incorrect syntax.
403	Is returned when userID does not have access to requested group
404	Is returned when groupID does not exist
500	Is returned when an unexpected error occurs while processing a request

Add user to a group

PUT /user/group/{group_id}/user_add/{user_id}/{access_level}

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
group_id	path	The identifier of the user group	Yes	string
user_id	path	The identifier of the user to be added	Yes	string
access_level	path	Access Level. One of admin or read	Yes	string

Responses

Code	Description
200
400	The request could not be understood by the server due to incorrect syntax.
403	Authentication required or user does not have access to change the group
404	Group or adding user is not exist
409	The user is already a member of a group
500	Is returned when an unexpected error occurs while processing a request

Remove user from the group

POST /user/group/{group_id}/user_remove/{user_id}}

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
group_id	path	The identifier of the user group	Yes	string
user_id	path	The identifier of the user to be removed	Yes	string

Responses

Code	Description
200
400	The request could not be understood by the server due to incorrect syntax.
403	Authentication required or user does not have access to change the group
404	Group or adding user is not exist or user_id is not the member of the group
500	Is returned when an unexpected error occurs while processing a request

Login user

POST /user/login

Parameters

Name	Located in	Description	Required	Schema
AuthUserId	header	UserId	Yes	string
EhrSystemId	header	The identifier of the system, typically a reverse domain identifier	No	string
Request	body	User authentication request	Yes	model.UserAuthRequest

Responses

Code	Description	Schema
200	OK	model.JWT
400	Password, EhrSystemId or userID incorrect
401	Password or userID incorrect
404	User with ID not exist
422	The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
500	Is returned when an unexpected error occurs while processing a request

Logout user

POST /user/logout

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer AccessToken	Yes	string
AuthUserId	header	UserId	Yes	string
Request	body	JWT	Yes	model.JWT

Responses

Code	Description
200	Successfully logged out
401	User unauthorized
422	The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
500	Is returned when an unexpected error occurs while processing a request

Refresh JWT

GET /user/refresh/

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer RefreshToken	Yes	string
AuthUserId	header	UserId	Yes	string

Responses

Code	Description	Schema
200	OK	model.JWT
401	User unauthorized
404	User with ID not exist
422	The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
500	Is returned when an unexpected error occurs while processing a request

Models

base.Archetyped

Name	Type	Description	Required
_type	base.ItemType		No
archetype_id	string		No
rm_version	string		No
template_id	string	TODO why link?	No

base.CodePhrase

Name	Type	Description	Required
_type	base.ItemType		No
code_string	string		No
preferred_term	string		No
terminology_id	string		No

base.DvCodedText

Name	Type	Description	Required
_type	base.ItemType		No
defining_code	base.CodePhrase		No
encoding	base.CodePhrase		No
formatting	string		No
hyperlink	base.DvURI		No
language	base.CodePhrase		No
mappings	base.TermMapping		No
value	string		No

base.DvDateTime

Name	Type	Description	Required
_type	base.ItemType		No
accuracy	base.DvDuration		No
value	string		No

base.DvDuration

Name	Type	Description	Required
_type	base.ItemType		No
accuracy			No
accuracyispercent	boolean		No
magnitude_status	boolean		No
normal_range	base.DvInterval-int64		No
normal_status	base.CodePhrase		No
otherreferenceranges	base.ReferenceRange-int64		No
value	string		No

base.DvEncapsulated

Name	Type	Description	Required
_type	base.ItemType		No
charset	base.CodePhrase		No
language	base.CodePhrase		No

base.DvIdentifier

Name	Type	Description	Required
_type	base.ItemType		No
assigner	string		No
id	string		No
issuer	string		No
type	string		No

base.DvInterval-int64

Name	Type	Description	Required
_type	base.ItemType		No
lower	integer		No
lower_included	boolean		No
lower_unbounded	boolean		No
upper	integer		No
upper_included	boolean		No
upper_unbounded	boolean		No

base.DvText

Name	Type	Description	Required
_type	base.ItemType		No
encoding	base.CodePhrase		No
formatting	string		No
hyperlink	base.DvURI		No
language	base.CodePhrase		No
mappings	[ base.TermMapping ]		No
value	string		No

base.DvURI

Name	Type	Description	Required
_type	base.ItemType		No
value	string		No

base.FeederAudit

Name	Type	Description	Required
feedersystemaudit	base.FeederAuditDetails		No
feedersystemitem_ids	base.DvIdentifier		No
original_content	base.DvEncapsulated		No
originatingsystemaudit	base.FeederAuditDetails		No
originatingsystemitem_ids	base.DvIdentifier		No

base.FeederAuditDetails

Name	Type	Description	Required
location	base.PartyIdentified		No
other_details	base.Locatable		No
provider	base.PartyIdentified		No
subject	base.PartyProxy		No
system_id	string		No
time	base.DvDateTime		No
version_id	string		No

base.Interval-base_DvDateTime

Name	Type	Description	Required
lower	base.DvDateTime		No
lower_included	boolean		No
lower_unbounded	boolean		No
upper	base.DvDateTime		No
upper_included	boolean		No
upper_unbounded	boolean		No

base.Interval-int64

Name	Type	Description	Required
lower	integer		No
lower_included	boolean		No
lower_unbounded	boolean		No
upper	integer		No
upper_included	boolean		No
upper_unbounded	boolean		No

base.ItemStructure

Name	Type	Description	Required
base.ItemStructure	object

base.ItemType

Name	Type	Description	Required
base.ItemType	string

base.Link

Name	Type	Description	Required
meaning	base.DvText		No
target	base.DvURI		No
type	base.DvText		No

base.Locatable

Name	Type	Description	Required
_type	base.ItemType		No
archetype_details	base.Archetyped		No
archetype_node_id	string		No
links	base.Link		No
name	base.DvText		No
uid	base.UIDBasedID		No

base.ObjectRef

Name	Type	Description	Required
id	string		No
namespace	string		No
type	string		No

base.Participation

Name	Type	Description	Required
function	base.DvText		No
mode	base.DvCodedText		No
performer	base.PartyProxy		No
time	base.Interval-base_DvDateTime		No

base.PartyIdentified

Name	Type	Description	Required
_type	base.ItemType		No
external_ref	base.ObjectRef		No
identifiers	base.DvIdentifier		No
name	string		No

base.PartyProxy

Name	Type	Description	Required
base.PartyProxy	object

base.ReferenceRange-int64

Name	Type	Description	Required
meaning	string		No
range	base.Interval-int64		No

base.TermMapping

Name	Type	Description	Required
match	integer		No
purpose	base.DvCodedText		No
target	base.CodePhrase		No

base.UIDBasedID

Name	Type	Description	Required
ObjectID	string		No

model.Composition

Name	Type	Description	Required
_type	base.ItemType		No
archetype_details	base.Archetyped		No
archetypenodeid	string		No
category	base.DvCodedText		No
composer	base.PartyProxy		No
content	[ ]		No
context	model.EventContext		No
language	base.CodePhrase		No
links	[ base.Link ]		No
name	base.DvText		No
territory	base.CodePhrase		No
uid	base.UIDBasedID		No

model.Directory

Name	Type	Description	Required
_type	base.ItemType		No
archetype_details	base.Archetyped		No
archetypenodeid	string		No
details	base.ItemStructure		No
feeder_audit	base.FeederAudit		No
folders	model.Directory		No
items	model.DirectoryItem		No
links	base.Link		No
name	base.DvText		No
uid	base.UIDBasedID		No

model.DirectoryItem

Name	Type	Description	Required
id	base.UIDBasedID		No
namespace	string		No
type	base.ItemType		No

model.DocAccessDocument

Name	Type	Description	Required
CID	string		No
description	string		No
level	string		No

model.DocAccessDocumentGroup

Name	Type	Description	Required
description	string		No
documents	model.DocAccessDocument		No
groupID	string		No
level	string		No
parentGroupID	string		No

model.DocAccessListResponse

Name	Type	Description	Required
documentGroups	model.DocAccessDocumentGroup		No
documents	model.DocAccessDocument		No

model.DocAccessSetRequest

Name	Type	Description	Required
accessLevel	string		No
cid	string		No
userID	string		No

model.EhrCreateRequest

Name	Type	Description	Required
_type	string		No
archetypenodeid	string		No
isModifiable	boolean		No
isQueryable	boolean		No
name	object		No
subject	object		No

model.EhrDocumentItem

Name	Type	Description	Required
name	string		No
timeCreated	string		No
uid	string		No

model.EhrStatusUpdate

Name	Type	Description	Required
_type	string		No
archetypenodeid	string		No
is_modifiable	boolean		No
is_queryable	boolean		No
name	object		No
other_details	object		No
subject	object		No
uid	object		No

model.EhrSummary

Name	Type	Description	Required
ehr_access	object		No
ehr_id	string		No
ehr_status	object		No
system_id	string		No
time_created	object		No

model.EventContext

Name	Type	Description	Required
end_time	base.DvDateTime		No
healthcarefacility	base.PartyIdentified		No
location	string		No
other_context	base.ItemStructure		No
participations	base.Participation		No
setting	base.DvCodedText		No
start_time	base.DvDateTime		No

model.ExternalRef

Name	Type	Description	Required
id	object		No
namespace	string		No
type	string		No

model.JWT

Name	Type	Description	Required
access_token	string		No
refresh_token	string		No

model.QueryColumn

Name	Type	Description	Required
name	string		No
path	string		No

model.QueryRequest

Name	Type	Description	Required
ehr_id	string		No
fetch	integer		No
offset	integer		No
q	string		No
query_parameters	object		No

model.QueryResponse

Name	Type	Description	Required
columns	model.QueryColumn		No
meta	object		No
name	string		No
q	string		No
rows	[ ]		No

model.QueryType

Name	Type	Description	Required
model.QueryType	string

model.StoredQuery

Name	Type	Description	Required
name	string		No
q	string		No
saved	string		No
type	model.QueryType		No
version	string		No

model.Template

Name	Type	Description	Required
archetype_id	string		No
concept	string		No
created_timestamp	string		No
template_id	string		No
version	string		No

model.UserAuthRequest

Name	Type	Description	Required
password	string		No
userID	string		No

model.UserCreateRequest

Name	Type	Description	Required
address	string		No
description	string		No
name	string		No
password	string		No
pictureURL	string		No
role	integer		No
userID	string		No

model.UserGroup

Name	Type	Description	Required
description	string		No
groupID	string		No
members	string		No
name	string		No

model.UserInfo

Name	Type	Description	Required
address	string		No
code	string		No
description	string		No
ehrID	string		No
name	string		No
pictureURL	string		No
role	string		No
timeCreated	string		No
userID	string		No

processing.EthereumTx

Name	Type	Description	Required
Kind	string		No
Status	string		No
comment	string		No
hash	string		No

processing.FileCoinTx

Name	Type	Description	Required
Kind	string		No
Status	string		No
cid	string		No
comment	string		No
dealCID	string		No
dealID	integer		No
minerAddress	string		No

processing.RequestResult

Name	Type	Description	Required
ethereum	processing.EthereumTx		No
filecoin	processing.FileCoinTx		No
kind	string		No
status	string		No

processing.RequestsResult

Name	Type	Description	Required
processing.RequestsResult	object