Versions Compared

Old Version 10

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.

Для формування API запитів, за допомогою яких Майданчик буде взаємодіяти взаємодії Майданчика з ЦБД рекомендуємо орієнтуватися на використовувати Swagger Prozorro.Sale

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


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

Для публікації обʼєкта в ЦБД необхідно передати запит з правильною структурою (body) із заповненими всіма обовʼязковими полями.

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

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

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

...

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


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

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

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

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

Цей запит НЕ змінюючи інші поля Процедури, а також не змінюючи вже існуючі в items[] обʼєкти item, додасть ще один item до items[]Для даної ситуації бажано НЕ використовувати PATCH всієї Процедури або PATCH , де в запиті передати поля, які не змінюються додає новий item без зміни інших полів Процедури чи існуючих об'єктів у items[]

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

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


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

...

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

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

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


Приклад 1:

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

...

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

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

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

...

Цей запит - це дія над конкретним обʼєктом 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), система може не обробити це як видалення, а просто зберегти поле з новим значенням.