You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

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

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


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

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

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

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

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


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

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

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

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

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

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

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


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

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

Правило:

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

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

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

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

Приклад 1:

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

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, то ЦБД поверне валідаційну помилку:

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

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

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

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

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

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[] НЕ потрібно передавати PATCH всього масиву items[] з повним набором полів у яких не змінюються і змінюються значення. Можна відредагувати конкрено поля і обʼєкти, які треба редагувати

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

  • Необхідно замінити значення в полях в обʼєкті document в масиві documents[]
  • Необхідно відредагувати значення в полях конкретного bid із масиву bids[]
  • та інші


Правила:

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

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


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





  • No labels