4. Архітектурний підхід REST API: основні принципи

Цей розділ визначає базові технічні правила реалізації підходу REST API у фреймворку відкритого банкінгу, включно з розміщенням параметрів повідомлень, структурою endpoint-ів, використанням заголовків, ідемпотентністю, керуванням процесом через гіперпосилання (HATEOAS) та узгодженими правилами обробки даних.

4.1. Розташування message параметрів

Визначення фреймворку відкритого банкінгу слідують підходу REST API. Цей підхід дозволяє передавати message параметри на різних рівнях:

• message параметри як частина рівня HTTP (HTTP header)
• message параметри шляхом визначення path ресурсу (URL path) з додатковими query параметрами
• message параметри як частина HTTP body

Параметри вмісту у відповідному HTTP body будуть закодовані або в синтаксисі JSON (обов’язковий для базових API), або додатково може використовуватись формат XML.

Параметри кодуються:

• у spinal-case (малими літерами) на рівні path,
• у spinal-case (з великої літери) на рівні HTTP header,
• у lowerCamelCase для query параметрів та content параметрів на основі JSON.

При визначенні API застосовується наступний принцип.

Message параметри як частина HTTP header:

• визначення content синтаксису,
• дані сертифіката та підпису, де це необхідно,
• дані на рівні протоколу, такі як Request Timestamps, ідентифікатори Request/Transaction або протокольні налаштування API client.

Message параметри як частина рівня path:

• Усі дані, що ідентифікують ресурс:
  • ідентифікація провайдера,
  • ідентифікація сервісу,
  • ідентифікація платіжного продукту,
  • ідентифікація рахунку,
  • ідентифікатор ресурсу.

Query Parameters:

• Додаткова інформація, необхідна для обробки GET запиту для фільтрації інформації.

Message параметри як частина HTTP body:

• вміст бізнес-даних,
• дані автентифікації PSU,
• інформація для обміну повідомленнями,
• гіперпосилання для керування повним процесом взаємодії TPP – ASPSP.

4.2. Структура API

API відкритого банкінгу орієнтований на ресурси. Ресурси можуть бути викликані через endpoint API:

https://{provider}/v2/{service}{?query-parameters}

з використанням додаткових параметрів вмісту {parameters}, де:

• {provider} — це host і path відповідного API, який далі не згадується. Host або path можуть містити інформацію про версію релізу ASPSP.
• v2 позначає фінальну версію 2.x фреймворку відкритого банкінгу.
• {service} може мати значення consents, payments, accounts для базових API, можливо, з додатковою інформацією про типи продуктів, як-от ідентифікація ресурсу та request скоуп.

Примітка: рекомендовано, щоб відповідний resourceId для ідентифікації конкретного ресурсу був UUID.

• {?query-parameters} — це параметри, що деталізують методи доступу на основі GET, наприклад, для фільтрації даних контенту.
• {parameters} — це атрибути контенту, визначені в JSON.

Ресурси

Структура request/response описується відповідно до наступних категорій:

• path: атрибути, закодовані в path, наприклад, payments/credit-transfers для {resource}.
• query parameters: атрибути, додані до path після знака ?, слід розглядати як атрибути фільтрації для методів доступу GET. Query параметри типу Boolean завжди повинні використовуватися у формі query-parameter=true або query-parameter=false.
• header: атрибути, закодовані в HTTP header request або response.
• request: атрибути в наборі параметрів вмісту request.
• response: атрибути в наборі вмісту параметрів response, визначені в JSON (обов’язковий для базових API) або XML, або text, де передбачений такий формат.

HTTP response codes, які можуть бути використані у фреймворку відкритого банкінгу, визначені в розділі 4.7.

Примітка: Для відповідей на основі JSON ця специфікація визначає атрибути body, які відповідають ASPSP API client після викликів API POST або PUT. ASPSP може повертати весь запитуваний ресурс у response, дотримуючись звичайних методологій REST API.

4.3. API Request Header параметри

Наступні headers визначені загально в цьому документі та будуть явно застосовані до опису сервісів лише через відповідні yaml файли. Така стисла документація призначена для підвищення читабельності специфікацій.

4.3.1. Transaction Initiation Request Headers

Transaction Initiation Request Headers (див. розділ 3.2.5 для визначення) є специфічними у фреймворку відкритого банкінгу. Ці повідомлення ініціації для бізнес-транзакцій не тільки передають інформацію, пов’язану з бізнесом, але також контекстні дані та дані, що керують використанням функцій фреймворку відкритого банкінгу. Ці headers визначені в цьому документі та будуть явно застосовані до визначень сервісів лише через відповідні yaml файли. Така стисла документація призначена для підвищення читабельності опису сервісів.

Фреймворк відкритого банкінгу передбачає наступні headers параметри для повідомлень Transaction Initiation Request Headers:

• контекстні дані PSU, див. розділ 8.1;
• дані ідентифікації PSU, див. розділ 8.2;
• налаштування підходу SCA, див. розділ 8.3–8.6;
• заголовок інформації про бренд клієнта, див. розділ 4.3.3.

Використання вищезгаданих headers може призвести до використання специфічних headers параметрів у Transaction Initiation Response, як визначено в наведених вище розділах.

4.3.2. Request Headers при створенні сервісних ресурсів

Request messages на створення сервісних ресурсів (див. розділ 3.2.6 визначення) мають різну специфікацію в межах різних сервісів у рамковій платформі відкритого банкінгу. Проте можна передбачити звичайний набір header параметрів, необхідних для створення відповідного ресурсу. Ці параметри включають, зокрема,

• Client Brand Logging Information Header.

Ці headers більше не будуть окремо згадуватися в інструкціях щодо реалізації відповідних сервісів, а лише загалом у цьому документі та відповідних yaml файлах. Інші, такі як headers авторизації OAuth2 або ідентифікатори API контрактів, залишаються явно визначеними в інструкціях щодо реалізації сервісу.

4.3.3. Header з інформацією про бренд API client

Наступний header може використовуватися у всіх Transaction Initiation Requests:

4.3.4. Headers пов’язані з підписом

Наступні параметри header можуть використовуватися у всіх header запитів API, де це застосовно:

• Headers пов’язані з підписом, див. розділ 7.

4.3.5. Технічні Headers

HTTP requests супроводжуються певними технічними headers, які не описуються цією специфікацією. Один з таких headers — заголовок date, який зазвичай додається автоматично на рівні протоколу HTTP системою API client.

Зверніть увагу, що процедура підписання повідомлень HTTP, визначена в розділі 7, вказує на спеціальний timestamp для фреймворку відкритого банкінгу, який сам захищений підписом.

4.4. Header параметри для ідемпотентності

Усі requests та responses у цьому фреймворку API супроводжуються унікальним X-Request-Id, UUID у requests та responses. X-Request-Id у відповіді дорівнює X-Request-Id у відповідному request.

Унікальність передбачає наступне:

Запит B з тим же X-Request-Id, що і запит A, повинен бути оброблений наступним чином для досягнення ідемпотентності:

1. Якщо бізнес-контент запиту B (наприклад, path, request параметри, body та header, визначені в цій специфікації) дорівнює бізнес-контенту запиту A, і якщо відхилення часу не надто велике (специфічне для реалізації), і якщо, можливо, внутрішній стан відповідного ресурсу не змінився за цей час: відповідь сервера на запит B також повинна дорівнювати відповіді на запит A.
2. В іншому випадку запитане повідомлення повинно бути відхилене з кодом відповіді 40x.

4.5. Процес управління API за допомогою гіперпосилань (HATEOAS)

Сервіси, визначені у фреймворку відкритого банкінгу, вимагають кількох запитів від API client до ASPSP. З Transaction Initiation Request, визначеним у кожному сервісі, ASPSP генерує презентацію ресурсу для відповідної бізнес-транзакції, наприклад, платіжного ресурсу або ресурсу згоди для доступу до AIS. Header location у відповіді зазвичай містить посилання на створений ресурс.

Крім того, ASPSP може вбудувати гіперпосилання разом із “тегом” для семантики цього гіперпосилання у відповідь на ці перші запити та на всі наступні запити в межах сервісів. Це гіперпосилання має бути URI-посиланням, як визначено в RFC 3986, і може бути:

• відносним посиланням, що рекомендується для економії місця, для host, починаючи, наприклад, з /psd2/v2/payments/credit-transfers, або
• глобальним посиланням, як-от https://www.testbank.com/psd2/v2/payments/credit-transfers/asdf-asdf-asdf-1234.

Глобальні посилання можуть знадобитися, наприклад, для перенаправлення. Тег гіперпосилання передає функціональність ресурсу, викликаного за допомогою посилання, наприклад, authorise-transaction. Це посилання вказує на те, що результати методу SCA повинні бути відправлені на ресурс, шляхом виклику цього посилання, щоб авторизувати, наприклад, платіжну операцію.

Керуючі гіперпосилання передаються в елементі даних _links з типом Link, він може містити одне або кілька гіперпосилань.

4.6. Посилання у Transaction Initiation Response

Повідомлення Transaction Initiation Response може містити багато гіперпосилань, які вказують на наступні кроки, необхідні для авторизації транзакції. Ці гіперпосилання не залежать від фактичної ініційованої транзакції. Тому вони визначені тут загально і не повторюються на рівні специфікацій, а лише у відповідних yaml файлах. Те ж саме стосується response повідомлень інших транзакцій, які можуть вимагати авторизації, наприклад, запит на створення згоди.

• scaRedirect: У випадку підходу SCA Redirect, ASPSP передає посилання, по якому потрібно перенаправити PSU.
• startAuthorisationWithPsuIdentification: Посилання на endpoint авторизації, де має бути створено підресурс авторизації під час завантаження даних ідентифікації PSU.
• status: Посилання для отримання статусу транзакції, що була ініційована. |

4.7. Коди відповідей HTTP

Код відповіді HTTP вказує на успішний або невдалий запит.

У відкритому банкінгу підтримуються наступні коди відповідей HTTP:

4.8. Мультивалютні рахунки

Визначення: мультивалютні рахунки — це рахунки, які містять різні cубрахунки або аналітичні рахунки, усі з яких об’єднується одним і тим же ідентифікатором рахунку, наприклад, IBAN. Субрахунки (аналітичні рахунки) є юридично різними рахунками і відрізняються валютою, залишками та транзакціями. Ідентифікатор рахунку, такий як IBAN разом з валютою, завжди унікально визначає субрахунок (аналітичний рахунок) мультивалютного рахунку.

Ця специфікація підтримує визначення мультивалютних рахунків як на рівні колекції, так і на рівні субрахунку (аналітичного рахунку). Атрибут даних валюти в відповідній структурі даних “Account Reference” дозволяє створювати структури, такі як:

{"iban":"UA553075600000026200019471278"}

або

{"iban":"UA525779700000026200019474278","currency":"EUR"}

Якщо рахунок є мультивалютним, то:

• перше посилання стосується сукупності всіх субрахунків, доступних за цим IBAN, і
• друге посилання стосується лише субрахунку в євро.

Ця специфікація розповсюджується на субрахунки (аналітичні рахунки) мультивалютних рахунків так само, як і на звичайні рахунки.

4.9. Правила включення меж інтервалів

Атрибути даних для дат, сум або інших дискретних даних іноді мають суфікс To або From, наприклад, dateTo, validTo. Ці атрибути завжди визначають інтервали. У всіх таких випадках значення From і To включає значення на відповідній межі запитуваного інтервалу. Це означає, що, наприклад, "dateFrom": "2025-04-05" означає, що 5 квітня 2025 року включено в запитуваний інтервал.