Versions Compared

Old Version 1

changes.mady.by.user Filip Kuzmin

Saved on

compared with

New Version Current

changes.mady.by.user Filip Kuzmin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Для взаємодії Майданчика з ЦБД рекомендуємо використовувати Swagger Prozorro.Sale

У цьому документі розглядаємо загальні правила роботи з API, що допоможуть правильно взаємодіяти з об'єктами ЦБД.


Публікація обʼєкта (POST)

Щоб опублікувати об'єкт у ЦБД, потрібно надіслати API-запит із правильною структурою body, заповнивши всі обов’язкові поля.

Якщо хоча б одне обов'язкове поле відсутнє, ЦБД поверне помилку:

Для публікації невистачає одного обовʼязкового поля:

Image Added

Не вистачає декількох обовʼязкових полів:

Image Added


Додавання об'єкта у вкладений масив

Якщо потрібно додати новий елемент до вкладеного масиву (наприклад, items[] у Процедурі), необхідно використовувати POST, а не PATCH.

Наприклад, в раніше опублікованій Процедурі необхідно додати в items[] ще один item

Потрібно використати запит:

Image Added

Цей запит додає новий item без зміни інших полів Процедури чи існуючих об'єктів у items[]

Note
titleНЕ рекомендується:

Використовувати PATCH, якщо в тілі запиту передаються всі поля Процедури (зокрема, ті, що не змінюються).


Інші приклади використання:

  • Організатору необхідно до раніше опублікованої процедури додати ще один document в documents[]:
  •  Image Added
  • Учасник публікує свою заяву на участь, чим, на рівні ЦБД, змінює bids[] тим, що додає в нього ще один обʼєкт bid
  • Image Added
  • Публікація Запитання (на рівні ЦБД - додати ще один обʼєкт question до questions[]
  • та інші схожі за логікою дії
Note
titleПравило:

Якщо потрібно ДОДАТИ до обʼєкта типу list[] ще один підобʼєкт - використовуємо POST

Редагування обʼєкта (PATCH)

Якщо виникає потреба змінити значення в полях раніше опублікованого обʼєкта, необхідно використовувати PATCH

Основні принципи використання PATCH:

  1. Передавайте лише ті поля, які змінюються.
  2. Якщо змінюється вкладений об'єкт, передавайте його повністю (включаючи всі вкладені поля, навіть якщо їх значення не змінюється).
  3. Не передавайте весь об'єкт Процедури, якщо змінюється лише окреме поле або вкладений об'єкт.


Приклад 1:

В опублікованій процедурі необхідно редагувати ТІЛЬКИ guarantee, необхідно передавати всі вкладені в guarantee поля: currency та amount

Expand
titleПриклад запиту
curl --location --request PATCH 'https://procedure-dev.prozorro.sale/api/procedures/67ac75cc33f701d712c6d315?acc_token=5d0f4461-353e-4a61-a5c6-19fcced1e908' \
--header 'Content-Type: application/json' \
--header 'Authorization: *****' \
--data '{
    "guarantee": {
        "currency": "UAH",
        "amount": 2000
    }
}

але немає потреби надсилати в запиті весь обʼєкт Процедури разом з полями в яких не змінюється значення.

При використанні PATCH для редагування вкладених об'єктів завжди передавайте весь вкладений об'єкт зі всіма його полями, навіть якщо змінюється лише одне з них.

Для деталізації прикладу, варто звернути увагу, що в зазначеному випадку може НЕ мінятись guarantee.currency, а тільки guarantee.amount, але так як використовується PATCH запит всієї процедури передавати в запиті необхідно guarantee{} та всі вкладені в нього поля. Якщо передати guarantee{} та лише поле, яке змінюється - guarantee.amount, то ЦБД поверне валідаційну помилку:

Image Added

Приклад 2: Редагування вкладеного обʼєкта

Для деяких полів типу list[] розроблено окремі endpoints, які дозволяють вносити зміни у вкладені обʼєкти.

Організатору в раніше опублікованій процедурі необхідно ЗМІНИТИ в items[] поля для якогось конкретного item, який вже присутній в процедурі.

Правильним рішенням буде використати:

Image Added

Цей запит - це дія над конкретним обʼєктом item, передавати в запиті на редагування потрібно тільки поля і моделі item, в які вносяться зміни.

Anchor
Example_1
Example_1

Expand
titleПриклад запиту

curl --location --request PATCH 'https://procedure-dev.prozorro.sale/api/procedures/67ac9c5833f701d712c6d935/items/82551f5e71c4431a82e7b65674f90381?acc_token=def1fb8d-84f2-4c14-9e88-dac8a5931702' \
--header 'Content-Type: application/json' \
--header 'Authorization: *****' \
--data '{
    "description": {
        "uk_UA": "Опис першого айтема РЕДАГУЮ"
    },
    "address": {
        "addressID": {
            "id": "4600000000",
            "scheme": "koatuu"
        },
        "streetAddress": {
            "uk_UA": "вул.РЕДАГУЮ, 222"
        },
        "locality": {
            "uk_UA": "Дніпро"
        },
        "region": {
            "uk_UA": "Дніпропетровська область"
        },
        "countryName": {
            "uk_UA": "Україна"
        }
    }
}'


В даному прикладі потреба відредагувати була для поля items[x].description та items[x].address.streetAddress. Але в запиті необхідно передати весь обʼєкт address, бо він є вкладеним у items[x]


Редагування окремого елемента в масиві

Якщо потрібно відредагувати конкретний item у масиві items[], не потрібно передавати весь масив. Достатньо передати лише той елемент масиву, який змінюється, зі зміненими полями.

Приклади використання:

  • Редагування окремого item у items[]
  • Оновлення полів у document в documents[]
  • Редагування конкретного bid у bids[]
  • та інші


Note
titleПравила:

  1. PATCH - Якщо потрібно змінити тільки окремі поля в обʼєкті без впливу на інші поля

  2. При редагуванні значень в полях обʼєкта, в PATCH запиті необхідно передавати тільки поля і вкладені обʼєкти в яких необхідно змінити значення в полях і НЕ передавати поля в яких не відбувається змін
  3. Якщо передати в PATCH запиті поле в якому не змінилось значення від попереднього, то ЦБД прийме це за зміну в полі + в обʼєкті оновиться dateModified
  4. Якщо необхідно редагувати певні поля у вкладеному обʼєкті, то необхідно передавати всі поля вкладеного обʼєкта, навіть ті, в яких не відбувається змін значень. Приклад


Видалення обʼєкта

Прямого видалення обʼєта в системі не передбачено, тому методи DELETE недоступні.

Якщо виникає необхідність в існуючому обʼєкті видалити значення в не обовʼязковому полі, неохідно скористатись PATCH запитом, де передати всі поля обʼєкта, окрім того, який потрібно видалити.

Але в історії обʼєкта все одно буде доступний "видалений" обʼєкт.

Загальне правило:

Щоб видалити значення необов'язкового поля, потрібно:
Відправити PATCH-запит,
Передати всі поля, крім того, яке потрібно видалити.

Info

Якщо відправити поле з порожнім значенням ("", null), система може не обробити це як видалення, а просто зберегти поле з новим значенням.