/
[DRAFT] [NEW] Get Composition by search params [API-007-011-001-0476]

ЕСОЗ - публічна документація

[DRAFT] [NEW] Get Composition by search params [API-007-011-001-0476]

Owned by Serhii.Matiushyn
Last updated: Jan 20, 2025 by Mariana Veremeieva (UA SoE eHealth)
4 min read

REST API method / Метод REST API (настанова) (remove the link block before publishing the document)

Properties of a REST API method document

Document type

Метод REST API

Document title

[DRAFT] [NEW] Get Composition by search params [API-007-011-001-0476]

Guideline ID

GUI-0011

Author

@Mariana Veremeieva (UA SoE eHealth)

Document version

1

Document status

DRAFT

Date of creation

ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)

Date of update

ХХ.ХХ.ХХХХ (дата зміни версії)

Method API ID

API-007-011-001-0476

Microservices (namespace)

ME

Component

Compositions_ME

Component ID

COM-007-011

Link на API-специфікацію

https://ehealthmedicalevents991v11.docs.apiary.io/#reference/medical-events/composition/get-composition-by-search-params

Resource

{{host}}//api.ehealth.gov.ua/api/patients/patient_id/compositions/search?encounter_id=3a0dcfd7-5348-4511-b46d-b2dc4b94ca98&type=DRIVERS&page=2&page_size=50

Scope

composition:read

Protocol type

REST

Request type

GET

Sync/Async

Async

Public/Private

Public

Purpose

This method allows to get a list of Composition in patient context. Also, this list can be filtered using search parameters.

Key points

  1. Only authenticated and authorized employee with appropriate scope can use this method

  2. Method returns a short information of Compositions that belongs to the specified patient.

  3. List can be filtered by search params.

Logic

Service logic

Service returns all Compositions related to the patient, filtered by submitted parameters:

  • Get all Composition by subject from compositions collection (MongoDB)

  • Filter list above by submitted search parameters

  • Render a response according to specification with a list of found Composition entities.

Configuration parameters

N/A

Dictionaries

Input parameters

Input parameter

Mandatory

Type

Description

Example

Input parameter

Mandatory

Type

Description

Example

1

patient_id

M

string($uuid)

unique patient identifie (encounterId)

25878134-7592-472a-adc1-f9532ce7f048

2

 encounter_id

 О

string($uuid)

encounter identifier linked to the Composition

89678f60-4cdc-4fe3-ae83-e8b3ebd35c59

3

context_episode_id

О

string($uuid)

episode identifier (composition.context_episode_id)

89678f60-4cdc-4fe3-ae83-e8b3ebd35c59

4

type

О

string(query)

type of the Composition - COMPOSITION_TYPES dictionary value

ADOPTION

5

category

О

string(query)

category of Composition - COMPOSITION_CATEGORIES dictionary value

ADOPTER

6

title

О

string

number of Composition (composition.title)

1111-P696-E34T-X4T2

7

status

О

string(query)

status of Composition - COMPOSITION_STATUS dictionary value

ENTERED_IN_ERROR

8

author

О

string($uuid)

author of Composition (composition.author.identifier.value)

97d57238-ffbe-4335-92ea-28d4de117ea2

9

attester

О

string($uuid)

Attester of Composition (composition.attester.party.value)

97d57238-ffbe-4335-92ea-28d4de117ea2

10

custodian

О

string($uuid)

LE where Composition was created (composition.custodian.identifier.value)

97d57238-ffbe-4335-92ea-28d4de117ea2

11

date_from

О

string(date)

the date from which the Composition was signed

2023-12-25

12

date_to

О

string(date)

the date to which the Composition was signed

2023-12-25

13

page

О

Number

filter list by page number

2

14

page_size

О

Number

a limit on the number of objects to be returned, between 1 and 100. Default: 50

30

Request structure

See on API-specification

Headers

Headers

Request data validation

Authorization

  • Verify the validity of access token

    • in case of error - return 401 “Invalid access token” in case of validation fails

  • Verify that token is not expired

    • in case of error - return 401 “Invalid access token”

  • Check user and client scopes in order to perform this action (scope = 'composition:read')

    • return 403 “Your scope does not allow to access this resource. Missing allowances: composition:read” in case of invalid scope(s)

  • Access to the resource is also managed by ABAC module

Validate Patient

  • Get Patient identifier from the URL

  • Check it exists in Mongo DB

    • Return 404 ('not found') in case of error

Search params

All search params are optional. Search with a few params executes according to the logical AND rule.

  • encounter_id

    • filter list by composition.encounter.identifier.value

  • context_episode_id

    • filter list by episode of care - composition.context_episode_id

  • type

    • filter list by composition.type.coding[*].code

  • category

    • filter list by composition.category.coding[*].code

  • title

    • filter list by composition.title

  • status

    • filter list by composition.status

  • author

    • filter list by composition.author.identifier.value

  • attester

    • filter list by composition.attester.party.value

  • custodian

    • filter list by composition.custodian.identifier.value

  • date_from

    • filter list by $.date_from <= composition.date

  • date_to

    • filter list by $.date_to >= composition.date

  • page

    • filter list by page number

  • page_size

    • a limit on the number of objects to be returned, between 1 and 100. Default: 50

Processing

N/A

Response structure examples

See on API-specification

{ "meta": { "code": 200, "url": "http://example.com/resource", "type": "object", "request_id": "req-adasdoijasdojsda" }, "data": [ { "id": "781ccc01-36a5-4cb7-bc4a-ea3dca500367", "status": "FINAL", "type": { "coding": [ { "system": "COMPOSITION_TYPES", "code": "DRIVERS" } ] }, "category": { "coding": [ { "system": "COMPOSITION_CATEGORIES", "code": "DRIVERS_GROUP1" } ] }, "date": "2018-08-02T10:45:16.000Z", "title": "98CC-P696-E34T-X4T2", "encounter": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "encounter" } ], "text": "string" }, "value": "781ccc01-36a5-4cb7-bc4a-ea3dca500367" } }, "custodian": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "legal_entity" } ], "text": "string" }, "value": "781ccc01-36a5-4cb7-bc4a-ea3dca500367" } }, "author": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "employee" } ], "text": "string" }, "value": "781ccc01-36a5-4cb7-bc4a-ea3dca500367" } }, "attester": [ { "mode": { "coding": [ { "system": "http://hl7.org/fhir/composition-attestation-mode", "code": "legal", "display": "Legal" } ] }, "party": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "employee" } ], "text": "string" }, "value": "781ccc01-36a5-4cb7-bc4a-ea3dca500367" } } } ], "context_episode_id": "DDD-23323-FDadc-32fd" } ], "paging": { "page": 2, "page_size": 50, "total_entries": 1000, "total_pages": 20 } }

HTTP status codes

Response code

HTTP Status code

Message

Internal name

Description

Response code

HTTP Status code

Message

Internal name

Description

1

Базові

2

 

401

Invalid access token

 

 

3

 

403

Your scope does not allow to access this resource. Missing allowances: composition:read

 

 

4

 

404

not found

 

 

5

Специфічні

6

 

 

 

 

 

Post-processing processes

N/A

Technical modules where the method is used

Название

ID ТМ

Статус

Название

ID ТМ

Статус

RC-V.2.1 [TM-011] Відхилення ЕР фармацевтом

TM0112

 

RC-V.2.1 [TM-011] Відхилення ЕР фармацевтом

 

 

 

ЕСОЗ - публічна документація