Для формування API запитів, за допомогою яких Майданчик буде взаємодіяти з ЦБД рекомендуємо орієнтуватися на Swagger Prozorro.Sale
В цьому документі розглянемо загальні правила, які допоможуть правильно взаємодіяти з обʼєктами ЦБД.
Публікація обʼєкта (POST)
Для публікації обʼєкта в ЦБД необхідно передати запит з правильною структурою (body) із заповненими всіма обовʼязковими полями.
Якщо в запиті НЕ передано одне чи декілька обовʼязкових полів, ЦБД поверне помилку:
Для публікації невистачає одного обовʼязкового поля:
Не вистачає декількох обовʼязкових полів:
Якщо існує потреба опублікувати вкладений в масив обʼєкт, необхідно використовувати також POST
Наприклад, в раніше опублікованій Процедурі необхідно додати в items[] ще один item
Потрібно використати запит
Цей запит НЕ змінюючи інші поля Процедури, а також не змінюючи вже існуючі в items[] обʼєкти item, додасть ще один item до items[]
Для даної ситуації бажано НЕ використовувати PATCH всієї Процедури або PATCH , де в запиті передати поля, які не змінюються.
Інші приклади використання:
- Організатору необхідно до раніше опублікованої процедури додати ще один document в documents[]:
- Учасник публікує свою заяву на участь, чим, на рівні ЦБД, змінює bids[] тим, що додає в нього ще один обʼєкт bid
- Публікація Запитання (на рівні ЦБД - додати ще один обʼєкт question до questions[]
- та інші схожі за логікою дії
Правило:
Якщо потрібно ДОДАТИ до обʼєкта типу list[] ще один підобʼєкт - використовуємо POST
Редагування обʼєкта (PATCH)
Якщо виникає потреба змінити значення в полях раніше опублікованої процедури, необхідно використовувати PATCH
Редагувати можна як весь обʼєкт повністю, так і вкладені підобʼєкти.
Приклад 1:
В опублікованій процедурі необхідно редагувати ТІЛЬКИ guarantee, необхідно передавати всі вкладені в guarantee поля: currency та amount
але немає потреби надсилати весь обʼєкт Процедури разом з полями в яких не змінюється значення.
Передавати в PATCH запиті необхідно тільки поля або вкладені обʼєкти зі всіма їх полями, в яких змінюються значення.
Для деталізації прикладу, варто звернути увагу, що в зазначеному випадку може НЕ мінятись guarantee.currency, а тільки guarantee.amount, але так як використовується PATCH запит всієї процедури передавати в запиті необхідно guarantee{} та всі вкладені в нього поля. Якщо передати guarantee{} та лише поле, яке змінюється - guarantee.amount, то ЦБД поверне валідаційну помилку:
Приклад 2: Редагування вкладеного обʼєкта
Для деяких полів типу list[] розроблено окремі endpoints, які дозволяють вносити зміни у вкладені обʼєкти.
Організатору в раніше опублікованій процедурі необхідно ЗМІНИТИ в items[] поля для якогось конкретного item, який вже присутній в процедурі.
Правильним рішенням буде використати:
Цей запит - це дія над конкретним обʼєктом item, передавати в запиті на редагування потрібно тільки поля і моделі item, в які вносяться зміни.
Для редагування в процедурі конкретного item із масиву items[] НЕ потрібно передавати PATCH всього масиву items[] з повним набором полів у яких не змінюються і змінюються значення. Можна відредагувати конкрено поля і обʼєкти, які треба редагувати
Інші приклади використання:
- Необхідно замінити значення в полях в обʼєкті document в масиві documents[]
- Необхідно відредагувати значення в полях конкретного bid із масиву bids[]
- та інші
Правила:
PATCH - Якщо потрібно змінити тільки окремі поля в обʼєкті без впливу на інші поля
- При редагуванні значень в полях обʼєкта, в PATCH запиті необхідно передавати тільки поля і вкладені обʼєкти в яких необхідно змінити значення в полях і НЕ передавати поля в яких не відбувається змін
- Якщо передати в PATCH запиті поле в якому не змінилось значення від попереднього, то ЦБД прийме це за зміну в полі + в обʼєкті оновиться dateModified
- Якщо необхідно редагувати певні поля у вкладеному обʼєкті, то необхідно передавати всі поля вкладеного обʼєкта, навіть ті, в яких не відбувається змін значень. Приклад