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

REST API Get Episode by id [API-007-006-001-0269]

By Serhii Boldin (SoE eHealth) (Unlicensed)
3 min

Properties of a REST API method document

Document type

Метод REST API

Document title

REST API Get Episode by id [API-007-006-001-0269]

Guideline ID

GUI-0011

Author

@Natalia Horodytska (SoE eHealth)

Document version

1

Document status

PROD

Date of creation

18.06.2024

Date of update

28.02.2025

Method API ID

API-007-006-001-0269

Microservices (namespace)

ME

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

https://esoz.docs.apiary.io/#reference/medical-events/episode-of-care/get-episode-by-id

Resource

{{host}}/api/patients/{{patient_id}}/episodes/{{episode_id}}

Scope

episode:read

Protocol type

REST

Request type

GET

Sync/Async

Sync

Public/Private

Public

Purpose

This API method is designed to get information about Episode by its identifier episode_id and patient identifier patient_id

Logic

N/A

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

Input parameter

Mandatory

Type

Description

Example

Input parameter

Mandatory

Type

Description

Example

1

patient_id

 

String

Patient identifier

70a9e15b-b71b-4caf-8f2e-ff247e8a5677

2

episode_id

 

String

Episode identifier

70a9e15b-b71b-4caf-8f2e-ff247e8a5677

Request structure

See on API-specification

Headers

Headers

Request data validation

Authorize

Request to process the request using a token in the headers

  1. Verify the validity of access token

    1. Return 401 in case validation fails

  2. Verify token is not expired

    1. in case error return 401 

  3. Check user scopes in order to perform this action (scope = 'episode:read')

    1. Return 403 in case invalid scope(s)

Access to the resource is also managed by ABAC module

Validate Patient

  1. Get Person identifier from the URL

    1. Check it exists in DB

      1. Return 404 ('not_found') in case of error

Processing

  1. Get episode by ID from episode collection (MongoDB)

  2. Validate data consistency:

    1. Ensure that requested episode relates to requested Patient (from URL)

      1. Return 404 ('not found') in case of error

  3. Render a response according to specification

Response structure examples

See on API-specification

{ "data": { "id": "90a9e15b-b71b-4caf-8f2e-ff247e8a5600", "inserted_at": "2018-08-02T10:45:16.000Z", "updated_at": "2018-08-02T10:45:16.000Z", "type": { "system": "eHealth/episode_types", "code": "primary_care" }, "status": "active", "name": "Діабет 2018", "current_diagnoses": [ { "condition": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "condition" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" }, "display_value": "null" }, "code": { "coding": [ { "system": "eHealth/ICPC2/conditions", "code": "A20" } ] }, "role": { "coding": [ { "system": "eHealth/diagnosis_roles", "code": "CC" } ] }, "rank": 1 } ], "diagnoses_history": [ { "date": "2018-08-02T10:45:16.000Z", "evidence": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "encounter" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" }, "display_value": "null" }, "diagnoses": [ { "condition": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "condition" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" }, "display_value": "null" }, "code": { "coding": [ { "system": "eHealth/ICPC2/conditions", "code": "A20" } ] }, "role": { "coding": [ { "system": "eHealth/diagnosis_roles", "code": "CC" } ] }, "rank": 1 }, { "condition": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "condition" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" }, "display_value": "null" }, "code": { "coding": [ { "system": "eHealth/ICPC2/conditions", "code": "A20" } ] }, "role": { "coding": [ { "system": "eHealth/diagnosis_roles", "code": "CC" } ] }, "rank": 1 } ] } ], "status_history": [ { "status": "active", "status reason": { "coding": [ { "system": "eHealth/episode_closing_reasons", "code": "cured" } ] }, "inserted_at": "2018-08-02T10:45:16.000Z" } ], "managing_organization": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "legal_entity" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" }, "display_value": "Медікал Солюшнc" }, "period": { "start": "2018-08-02T10:45:16.000Z", "end": "2018-08-03T10:45:16.000Z" }, "care_manager": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "employee" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" }, "display_value": "null" }, "closing_summary": "Носові шляхи вільні, горло рожеве, температура в нормі", "status_reason": { "coding": [ { "system": "eHealth/episode_closing_reasons", "code": "cured" } ] }, "explanatory_letter": "Епізод був відмінений у зв'язку з помилкою при виборі пацієнта" }, "meta": { "code": 200, "url": "http://example.com/resource", "type": "object", "request_id": "req-adasdoijasdojsda" } }

HTTP status codes

Response code

HTTP Status code

Message

Internal name

Description

Response code

HTTP Status code

Message

Internal name

Description

1

Базові

2

 

401

Access token validation failed

 

 

3

 

403

Invalid scope

 

 

4

 

404

Not found

 

 

5

Специфічні

6

 

 

 

 

 

Post-processing processes

N/A

Technical modules where the method is used

 

 

Related content

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