From b41d68cc8cd426072def8878ab21fcf3b1137bad Mon Sep 17 00:00:00 2001 From: Sebastian Iancu Date: Tue, 12 Mar 2024 21:40:26 +0100 Subject: [PATCH] adding AGENT resource (#99 SPECITS-70) --- specifications/demographic.openapi.yaml | 25 +++++++++++++ specifications/headers/Location_AGENT.yaml | 6 ++++ .../Location_VERSIONED_AGENT_VERSION.yaml | 6 ++++ specifications/operations/agent_create.yaml | 25 +++++++++++++ specifications/operations/agent_delete.yaml | 20 +++++++++++ specifications/operations/agent_get.yaml | 23 ++++++++++++ specifications/operations/agent_update.yaml | 35 +++++++++++++++++++ .../operations/versioned_agent_get.yaml | 13 +++++++ .../versioned_agent_revision_history.yaml | 13 +++++++ .../versioned_agent_version_get_at_time.yaml | 16 +++++++++ .../versioned_agent_version_get_by_id.yaml | 14 ++++++++ .../path/versioned_object_uid_AGENT.yaml | 9 +++++ .../responses/200_AGENT_retrieved.yaml | 11 ++++++ .../responses/200_AGENT_updated.yaml | 11 ++++++ .../responses/200_VERSIONED_AGENT.yaml | 6 ++++ .../200_VERSION_of_AGENT_at_time.yaml | 11 ++++++ .../responses/200_VERSION_of_AGENT_by_id.yaml | 6 ++++ specifications/responses/201_AGENT.yaml | 12 +++++++ .../responses/204_AGENT_deleted.yaml | 7 ++++ .../409_AGENT_with_uid_based_id.yaml | 8 +++++ specifications/responses/412_AGENT.yaml | 8 +++++ .../demographic/UMImportedVersionOfAgent.yaml | 15 ++++++++ .../demographic/UMOriginalVersionOfAgent.yaml | 13 +++++++ .../schemas/demographic/UVersionOfAgent.yaml | 9 +++++ .../schemas/demographic/VersionOfAgent.yaml | 18 ++++++++++ .../schemas/demographic/VersionedAgent.yaml | 21 +++++++++++ 26 files changed, 361 insertions(+) create mode 100644 specifications/headers/Location_AGENT.yaml create mode 100644 specifications/headers/Location_VERSIONED_AGENT_VERSION.yaml create mode 100644 specifications/operations/agent_create.yaml create mode 100644 specifications/operations/agent_delete.yaml create mode 100644 specifications/operations/agent_get.yaml create mode 100644 specifications/operations/agent_update.yaml create mode 100644 specifications/operations/versioned_agent_get.yaml create mode 100644 specifications/operations/versioned_agent_revision_history.yaml create mode 100644 specifications/operations/versioned_agent_version_get_at_time.yaml create mode 100644 specifications/operations/versioned_agent_version_get_by_id.yaml create mode 100644 specifications/parameters/path/versioned_object_uid_AGENT.yaml create mode 100644 specifications/responses/200_AGENT_retrieved.yaml create mode 100644 specifications/responses/200_AGENT_updated.yaml create mode 100644 specifications/responses/200_VERSIONED_AGENT.yaml create mode 100644 specifications/responses/200_VERSION_of_AGENT_at_time.yaml create mode 100644 specifications/responses/200_VERSION_of_AGENT_by_id.yaml create mode 100644 specifications/responses/201_AGENT.yaml create mode 100644 specifications/responses/204_AGENT_deleted.yaml create mode 100644 specifications/responses/409_AGENT_with_uid_based_id.yaml create mode 100644 specifications/responses/412_AGENT.yaml create mode 100644 specifications/schemas/demographic/UMImportedVersionOfAgent.yaml create mode 100644 specifications/schemas/demographic/UMOriginalVersionOfAgent.yaml create mode 100644 specifications/schemas/demographic/UVersionOfAgent.yaml create mode 100644 specifications/schemas/demographic/VersionOfAgent.yaml create mode 100644 specifications/schemas/demographic/VersionedAgent.yaml diff --git a/specifications/demographic.openapi.yaml b/specifications/demographic.openapi.yaml index f743a78f..34bf2123 100644 --- a/specifications/demographic.openapi.yaml +++ b/specifications/demographic.openapi.yaml @@ -22,6 +22,28 @@ servers: description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix. security: [] paths: + '/demographic/agent': + post: + $ref: ./operations/agent_create.yaml + '/demographic/agent/{uid_based_id}': + get: + $ref: ./operations/agent_get.yaml + put: + $ref: ./operations/agent_update.yaml + delete: + $ref: ./operations/agent_delete.yaml + '/demographic/versioned_agent/{versioned_object_uid}': + get: + $ref: ./operations/versioned_agent_get.yaml + '/demographic/versioned_agent/{versioned_object_uid}/revision_history': + get: + $ref: ./operations/versioned_agent_revision_history.yaml + '/demographic/versioned_agent/{versioned_object_uid}/version': + get: + $ref: ./operations/versioned_agent_version_get_at_time.yaml + '/demographic/versioned_agent/{versioned_object_uid}/version/{version_uid}': + get: + $ref: ./operations/versioned_agent_version_get_by_id.yaml '/demographic/person': post: $ref: ./operations/person_create.yaml @@ -51,6 +73,9 @@ paths: get: $ref: ./operations/contribution_get.yaml tags: + - name: AGENT + description: | + Management of the [AGENT](https://specifications.openehr.org/releases/RM/latest/demographic.html#_agent_class) and the associated [VERSIONED_AGENT](https://specifications.openehr.org/releases/RM/latest/demographic.html#_versioned_party_class) resource. - name: PERSON description: | Management of the [PERSON](https://specifications.openehr.org/releases/RM/latest/demographic.html#_person_class) and the associated [VERSIONED_PERSON](https://specifications.openehr.org/releases/RM/latest/demographic.html#_versioned_party_class) resource. diff --git a/specifications/headers/Location_AGENT.yaml b/specifications/headers/Location_AGENT.yaml new file mode 100644 index 00000000..8379c4db --- /dev/null +++ b/specifications/headers/Location_AGENT.yaml @@ -0,0 +1,6 @@ +description: | + The `Location` response header indicates the URL of the AGENT resource. +schema: + type: string + format: url + example: 'https://openEHRSys.example.com/v1/demographic/agent/6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2' diff --git a/specifications/headers/Location_VERSIONED_AGENT_VERSION.yaml b/specifications/headers/Location_VERSIONED_AGENT_VERSION.yaml new file mode 100644 index 00000000..8b8cacdb --- /dev/null +++ b/specifications/headers/Location_VERSIONED_AGENT_VERSION.yaml @@ -0,0 +1,6 @@ +description: | + The `Location` response header indicates the URL of the VERSION resource. +schema: + type: string + format: url + example: 'https://openEHRSys.example.com/v1/demographic/versioned_agent/6cb19121-4307-4648-9da0-d62e4d51f19b/version/6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1' diff --git a/specifications/operations/agent_create.yaml b/specifications/operations/agent_create.yaml new file mode 100644 index 00000000..fffbd1b1 --- /dev/null +++ b/specifications/operations/agent_create.yaml @@ -0,0 +1,25 @@ +operationId: agent_create +summary: Create AGENT +description: | + Creates the first version of a new AGENT. +tags: + - AGENT +parameters: + - $ref: ../parameters/header/Prefer.yaml +requestBody: + description: | + The AGENT. + content: + application/json: + schema: + $ref: ../schemas/demographic/Agent.yaml + required: true +responses: + '201': + $ref: ../responses/201_AGENT.yaml + '400': + $ref: ../responses/400.yaml + '422': + $ref: ../responses/422.yaml + '404': + $ref: ../responses/404.yaml diff --git a/specifications/operations/agent_delete.yaml b/specifications/operations/agent_delete.yaml new file mode 100644 index 00000000..c01bdda4 --- /dev/null +++ b/specifications/operations/agent_delete.yaml @@ -0,0 +1,20 @@ +operationId: agent_delete +summary: Delete AGENT +description: | + 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. + +tags: + - AGENT +parameters: + - $ref: ../parameters/path/uid_based_id_as_version_uid.yaml +responses: + '204': + $ref: ../responses/204_AGENT_deleted.yaml + '400': + $ref: ../responses/400_already_deleted.yaml + '404': + $ref: ../responses/404.yaml + '409': + $ref: ../responses/409_AGENT_with_uid_based_id.yaml diff --git a/specifications/operations/agent_get.yaml b/specifications/operations/agent_get.yaml new file mode 100644 index 00000000..23905f65 --- /dev/null +++ b/specifications/operations/agent_get.yaml @@ -0,0 +1,23 @@ +operationId: agent_get +summary: Get AGENT +description: | + 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](overview.html#tag/Resources/Resource-identification) for more details about the identifiers usage and meaning. +tags: + - AGENT +parameters: + - $ref: ../parameters/path/uid_based_id.yaml + - $ref: ../parameters/query/version_at_time.yaml +responses: + '200': + $ref: ../responses/200_AGENT_retrieved.yaml + '204': + $ref: ../responses/204_because_deleted_at_time.yaml + '404': + $ref: ../responses/404_not_found_or_no_version_at_time.yaml diff --git a/specifications/operations/agent_update.yaml b/specifications/operations/agent_update.yaml new file mode 100644 index 00000000..3eb256e2 --- /dev/null +++ b/specifications/operations/agent_update.yaml @@ -0,0 +1,35 @@ +operationId: agent_update +summary: Update AGENT +description: | + 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. +tags: + - AGENT +parameters: + - $ref: ../parameters/path/uid_based_id_as_versioned_object_uid.yaml + - $ref: ../parameters/header/If-Match.yaml + - $ref: ../parameters/header/Prefer.yaml +requestBody: + description: | + The new AGENT. + content: + application/json: + schema: + $ref: ../schemas/demographic/Agent.yaml + required: true +responses: + '200': + $ref: ../responses/200_AGENT_updated.yaml + '400': + $ref: ../responses/400.yaml + '404': + $ref: ../responses/404.yaml + '412': + $ref: ../responses/412_AGENT.yaml + '422': + $ref: ../responses/422.yaml diff --git a/specifications/operations/versioned_agent_get.yaml b/specifications/operations/versioned_agent_get.yaml new file mode 100644 index 00000000..bb19f442 --- /dev/null +++ b/specifications/operations/versioned_agent_get.yaml @@ -0,0 +1,13 @@ +operationId: versioned_agent_get +summary: Get versioned AGENT +description: | + Retrieves a VERSIONED_AGENT identified by `versioned_object_uid`. +tags: + - AGENT +parameters: + - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml +responses: + '200': + $ref: ../responses/200_VERSIONED_AGENT.yaml + '404': + $ref: ../responses/404.yaml diff --git a/specifications/operations/versioned_agent_revision_history.yaml b/specifications/operations/versioned_agent_revision_history.yaml new file mode 100644 index 00000000..2961b9af --- /dev/null +++ b/specifications/operations/versioned_agent_revision_history.yaml @@ -0,0 +1,13 @@ +operationId: versioned_agent_revision_history +summary: Get versioned AGENT revision history +description: | + Retrieves revision history of the VERSIONED_AGENT identified by `versioned_object_uid`. +tags: + - AGENT +parameters: + - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml +responses: + '200': + $ref: ../responses/200_REVISION_HISTORY.yaml + '404': + $ref: ../responses/404.yaml diff --git a/specifications/operations/versioned_agent_version_get_at_time.yaml b/specifications/operations/versioned_agent_version_get_at_time.yaml new file mode 100644 index 00000000..e1c0eb8f --- /dev/null +++ b/specifications/operations/versioned_agent_version_get_at_time.yaml @@ -0,0 +1,16 @@ +operationId: versioned_agent_version_get_at_time +summary: Get versioned AGENT version at time +description: | + Retrieves a VERSION from the VERSIONED_AGENT identified by `versioned_object_uid`. + + If `version_at_time` is supplied, retrieves the VERSION extant _at specified time_, otherwise retrieves the _latest_ VERSION. +tags: + - AGENT +parameters: + - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml + - $ref: ../parameters/query/version_at_time.yaml +responses: + '200': + $ref: ../responses/200_VERSION_of_AGENT_at_time.yaml + '404': + $ref: ../responses/404_not_found_or_no_version_at_time.yaml diff --git a/specifications/operations/versioned_agent_version_get_by_id.yaml b/specifications/operations/versioned_agent_version_get_by_id.yaml new file mode 100644 index 00000000..4b545a5a --- /dev/null +++ b/specifications/operations/versioned_agent_version_get_by_id.yaml @@ -0,0 +1,14 @@ +operationId: versioned_composition_version_get_by_id +summary: Get versioned AGENT version by id +description: | + Retrieves a VERSION identified by `version_uid` of a VERSIONED_AGENT identified by `versioned_object_uid`. +tags: + - AGENT +parameters: + - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml + - $ref: ../parameters/path/version_uid.yaml +responses: + '200': + $ref: ../responses/200_VERSION_of_AGENT_by_id.yaml + '404': + $ref: ../responses/404.yaml diff --git a/specifications/parameters/path/versioned_object_uid_AGENT.yaml b/specifications/parameters/path/versioned_object_uid_AGENT.yaml new file mode 100644 index 00000000..d09d480f --- /dev/null +++ b/specifications/parameters/path/versioned_object_uid_AGENT.yaml @@ -0,0 +1,9 @@ +name: versioned_object_uid +in: path +description: | + VERSIONED_AGENT identifier taken from VERSIONED_AGENT.uid.value. +required: true +style: simple +schema: + type: string + example: '6cb19121-4307-4648-9da0-d62e4d51f19b' diff --git a/specifications/responses/200_AGENT_retrieved.yaml b/specifications/responses/200_AGENT_retrieved.yaml new file mode 100644 index 00000000..50f69d45 --- /dev/null +++ b/specifications/responses/200_AGENT_retrieved.yaml @@ -0,0 +1,11 @@ +description: | + `200 OK` is returned when the requested AGENT is successfully retrieved. +headers: + ETag: + $ref: ../headers/ETag.yaml + Location: + $ref: ../headers/Location_AGENT.yaml +content: + application/json: + schema: + $ref: ../schemas/demographic/Agent.yaml diff --git a/specifications/responses/200_AGENT_updated.yaml b/specifications/responses/200_AGENT_updated.yaml new file mode 100644 index 00000000..18095ef2 --- /dev/null +++ b/specifications/responses/200_AGENT_updated.yaml @@ -0,0 +1,11 @@ +description: | + `200 OK` is returned when the AGENT is successfully updated and the updated resource is returned in the body when `Prefer` header value is `return=representation`. +headers: + ETag: + $ref: ../headers/ETag.yaml + Location: + $ref: ../headers/Location_AGENT.yaml +content: + application/json: + schema: + $ref: ../schemas/demographic/Agent.yaml diff --git a/specifications/responses/200_VERSIONED_AGENT.yaml b/specifications/responses/200_VERSIONED_AGENT.yaml new file mode 100644 index 00000000..55c72678 --- /dev/null +++ b/specifications/responses/200_VERSIONED_AGENT.yaml @@ -0,0 +1,6 @@ +description: | + `200 OK` is returned when the requested VERSIONED_AGENT is successfully retrieved. +content: + application/json: + schema: + $ref: ../schemas/demographic/VersionedAgent.yaml diff --git a/specifications/responses/200_VERSION_of_AGENT_at_time.yaml b/specifications/responses/200_VERSION_of_AGENT_at_time.yaml new file mode 100644 index 00000000..be81d31f --- /dev/null +++ b/specifications/responses/200_VERSION_of_AGENT_at_time.yaml @@ -0,0 +1,11 @@ +description: | + `200 OK` is returned when the requested VERSION is successfully retrieved. +headers: + ETag: + $ref: ../headers/ETag_VERSION.yaml + Location: + $ref: ../headers/Location_VERSIONED_AGENT_VERSION.yaml +content: + application/json: + schema: + $ref: ../schemas/demographic/UVersionOfAgent.yaml diff --git a/specifications/responses/200_VERSION_of_AGENT_by_id.yaml b/specifications/responses/200_VERSION_of_AGENT_by_id.yaml new file mode 100644 index 00000000..c986ef71 --- /dev/null +++ b/specifications/responses/200_VERSION_of_AGENT_by_id.yaml @@ -0,0 +1,6 @@ +description: | + `200 OK` is returned when the requested VERSION is successfully retrieved. +content: + application/json: + schema: + $ref: ../schemas/demographic/UVersionOfAgent.yaml diff --git a/specifications/responses/201_AGENT.yaml b/specifications/responses/201_AGENT.yaml new file mode 100644 index 00000000..445817c4 --- /dev/null +++ b/specifications/responses/201_AGENT.yaml @@ -0,0 +1,12 @@ +description: | + `201 Created` is returned when the AGENT was created. + Content body is only returned when `Prefer` header has `return=representation`, otherwise only headers are returned. +headers: + ETag: + $ref: ../headers/ETag.yaml + Location: + $ref: ../headers/Location_AGENT.yaml +content: + application/json: + schema: + $ref: ../schemas/demographic/Agent.yaml diff --git a/specifications/responses/204_AGENT_deleted.yaml b/specifications/responses/204_AGENT_deleted.yaml new file mode 100644 index 00000000..e0ce983f --- /dev/null +++ b/specifications/responses/204_AGENT_deleted.yaml @@ -0,0 +1,7 @@ +description: | + `204 No Content` is returned when AGENT was deleted. +headers: + ETag: + $ref: ../headers/ETag.yaml + Location: + $ref: ../headers/Location_AGENT.yaml diff --git a/specifications/responses/409_AGENT_with_uid_based_id.yaml b/specifications/responses/409_AGENT_with_uid_based_id.yaml new file mode 100644 index 00000000..203fda86 --- /dev/null +++ b/specifications/responses/409_AGENT_with_uid_based_id.yaml @@ -0,0 +1,8 @@ +description: | + `409 Conflict` is returned when supplied `uid_based_id` doesn't match the latest version. + Returns also latest version in the `Location` and `ETag` headers. +headers: + ETag: + $ref: ../headers/ETag.yaml + Location: + $ref: ../headers/Location_AGENT.yaml diff --git a/specifications/responses/412_AGENT.yaml b/specifications/responses/412_AGENT.yaml new file mode 100644 index 00000000..2b1bea94 --- /dev/null +++ b/specifications/responses/412_AGENT.yaml @@ -0,0 +1,8 @@ +description: | + `412 Precondition Failed` is returned when `If-Match` request header doesn't match the latest version on the service side. + Returns also latest `version_uid` in the `Location` and `ETag` headers. +headers: + ETag: + $ref: ../headers/ETag.yaml + Location: + $ref: ../headers/Location_AGENT.yaml diff --git a/specifications/schemas/demographic/UMImportedVersionOfAgent.yaml b/specifications/schemas/demographic/UMImportedVersionOfAgent.yaml new file mode 100644 index 00000000..0ee4ad95 --- /dev/null +++ b/specifications/schemas/demographic/UMImportedVersionOfAgent.yaml @@ -0,0 +1,15 @@ +title: IMPORTED_VERSION +type: object +allOf: + - $ref: ../common/ImportedVersion.yaml +required: + - _type +properties: + _type: + type: string + enum: [IMPORTED_VERSION] + data: + $ref: ../demographic/Agent.yaml + item: + $ref: ../demographic/UMOriginalVersionOfAgent.yaml +x-discriminator-value: IMPORTED_VERSION diff --git a/specifications/schemas/demographic/UMOriginalVersionOfAgent.yaml b/specifications/schemas/demographic/UMOriginalVersionOfAgent.yaml new file mode 100644 index 00000000..a4acc728 --- /dev/null +++ b/specifications/schemas/demographic/UMOriginalVersionOfAgent.yaml @@ -0,0 +1,13 @@ +title: ORIGINAL_VERSION +type: object +allOf: + - $ref: ../common/OriginalVersion.yaml +required: + - _type +properties: + _type: + type: string + enum: [ORIGINAL_VERSION] + data: + $ref: ../demographic/Agent.yaml +x-discriminator-value: ORIGINAL_VERSION diff --git a/specifications/schemas/demographic/UVersionOfAgent.yaml b/specifications/schemas/demographic/UVersionOfAgent.yaml new file mode 100644 index 00000000..c8c647cb --- /dev/null +++ b/specifications/schemas/demographic/UVersionOfAgent.yaml @@ -0,0 +1,9 @@ +title: VERSION +oneOf: + - $ref: ../demographic/UMOriginalVersionOfAgent.yaml + - $ref: ../demographic/UMImportedVersionOfAgent.yaml +discriminator: + propertyName: _type + mapping: + ORIGINAL_VERSION: ../demographic/UMOriginalVersionOfAgent.yaml + IMPORTED_VERSION: ../demographic/UMImportedVersionOfAgent.yaml diff --git a/specifications/schemas/demographic/VersionOfAgent.yaml b/specifications/schemas/demographic/VersionOfAgent.yaml new file mode 100644 index 00000000..b20d2163 --- /dev/null +++ b/specifications/schemas/demographic/VersionOfAgent.yaml @@ -0,0 +1,18 @@ +title: VERSION +type: object +description: A VERSION resource +required: + - contribution + - commit_audit + - data +properties: + _type: + type: string + contribution: + $ref: ../base_types/ObjectRef.yaml + signature: + type: string + commit_audit: + $ref: ../common/AuditDetails.yaml + data: + $ref: ../demographic/Agent.yaml diff --git a/specifications/schemas/demographic/VersionedAgent.yaml b/specifications/schemas/demographic/VersionedAgent.yaml new file mode 100644 index 00000000..ffecd3bc --- /dev/null +++ b/specifications/schemas/demographic/VersionedAgent.yaml @@ -0,0 +1,21 @@ +title: VERSIONED_AGENT +description: A VERSIONED_AGENT resource +type: object +allOf: + - $ref: ../common/VersionedObject.yaml +properties: + _type: + type: string + default: VERSIONED_AGENT +x-discriminator-value: VERSIONED_AGENT +example: + uid: + value: 8849182c-82ad-4088-a07f-48ead4180515 + owner_id: + id: + _type: HIER_OBJECT_ID + value: 7d44b88c-4199-4bad-97dc-d78268e01398 + namespace: local + type: EHR + time_created: + value: '2015-01-20T19:30:22.765+01:00'