REST

Сторінка технічної документації є баченням майбутньої реалізації, актуальність якого може бути застарілою.

Методи

Name

Description

GET

Використовується для отримання об’єктів. Не змінює стан ресурсу

PUT

Використовується для зміни вже існуючого ресурсу з вказанням id ( /pd-processing-consent-rcnt/1) or to modify an existing resource.

DELETE

Used to remove a specific resource, that is defined by a unique URL (e.g., /pd-processing-consent-rcnt/1). For filtered or batch removes POST is used instead.

POST

Used for: to add a resource without known identifier beforehand (e.g., pd-processing-consent-rcnt/1); for filtered or batched removes; to search/filter resources; for any other requests that cannot guarantee idempotence.

Status codes

  • 2XX - Успішне виконання

  • 4XX - Помилка

  • 4XX - Логічна помилка (описана в окремій секції);

  • 5XX - Помилка сталась на стороні сервера

Code Description Body

200

OK with result

201

OK when a resource was successfully created

204

OK без тіла використовується у випадках PUT/DELETE

400

Bad request meaning input data was incorrect (e.g., wrong field type)

401

Помилка аутентифікації (відсутній токен або цифровий підпис)

403

Недостатньо прав для виконання операції (роль користувача не передбачає доступу до даного ресурсу

With body

404

Ресурс не знайдено (e.g., /pd-processing-consent-rcnt/1 can return 404 if consent "1" is not found)

No Body

420

Зарезервований код для логічних помилок ()

422

Помилка валідації, запит містить

500

Internal server error

501

Не імплементовано (використовується для заглушок)

Формати повертаємих даних

  • Для полів які мають тип список або масив (arrays/lists) null значення є недопустимим. В таких випадках має повертатись порожній список ({"emptyList":[]})

  • Формат дат і дат із часом -

Доступні HTTP заголовки (Headers)

Ім’я

Опис

Походження

X-Access-Token

[Обов’язкове] Підписаний JWT токен

Kong/Upstream

X-Id-Token

Не підписаний JWT токен (*)

Kong

X-Userinfo

User Info from JWT

Kong

X-Digital-Signature

[Обов’язкове] Base64 КЕП підпис

Upstream

x-request-id

[Обов’язкове] Ідентифікатор запиту згенерований Istio (для Kiali)

Istio

x-b3-traceid

[Обов’язкове] Ідентифікатор запиту згенерований Istio (для Jaeger)

Istio

x-b3-spanid

[Обов’язкове] Ідентифікатор запиту згенерований Istio (для Jaeger)

Istio

source-system

[Обов’язкове] Назва системи яка викликає дата фабрику (приклади значень: mdtuddm/trembita)

Upstream

source-application

[Обов’язкове] Назва сервісу який з якого викликається дата фабрика (приклад: портал чиновника)

Upstream

source-business-process

для Low-Code назва бізнес процесу в рамках якого викликається дата фабрика

Upstream

source-business-id

для Low-Code Ідентифікатор сутності (instance) бізнес процесу

Upstream

Logical\regular errors

Logical error is a special error/condition that can be handled by a client. For example, 401 might mean that a users signature has expired, or 404 – that something wasn’t found. The logic behind this is to allow special conditions on some of requests: if condition is not met upon a request, then a client application can offer something to a user, or do additional steps. Contrary to logical errors, regular errors like 400 or 500 mean that something failed due to a bug or unavailable service, such errors should not be handled by a client application and a simple message for a user should be enough.

Validation Errors

Currently validation errors considered as a regular client error, which means there is a bug either on client side or server side if a validation error is returned; as a result, they should not be handled by a client application.

Error Structure

{
    "error": {
        "trace_id": "<trace_id>", // generated & propagated by Istio Envoy -> support ticket
        "code": "<internal_error_code>", // error codes for granular exception handling
        "message": "Something bad happened", // error code specific developer message
        "localizedMessage": "[optional]" // error code specific user-friendly message (depends on localization strategy)
    }
}