Відповіді

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

Коди стану

У будь-якому випадку API повинен повернути Код стану HTTP, що вказуватиме природу помилки (див. внизу), з тілом відповіді у форматі JSON, що міститиме додаткову інформацію.

200
Успіх. Якщо це був запит про інформацію, то вона буде доступна у data полі на верхньому рівні тіла відповіді.
201
Створено. Його інформація доступна у data полі на верхньому рівні тіла відповіді. API URL, де об’єкт можна прочитати, міститься у Location заголовку відповіді.
400
Неправильний запит. Зазвичай це відбувається через відсутній або неправильний параметр. Перевірте документацію та синтаксис вашого запиту і спробуйте ще раз.
401
Несанкційонований доступ. Не було надано дійсного API ключа разом із запитом, тому API не може зв’язати користувача із запитом.
403
Заборонено. API ключ та синтаксис запиту були дійсними, але сервер відмовляється виконати запит. Це може статися, якщо ви пробуєте прочитати або записати об’єкти чи властивості, до яких не маєте доступу.
404
Ресурс не знайдено. Або даний метод та шлях запиту не вказують відому дію для API, або об’єкт, вказаний у запиті, не існує.
409
Конфлікт при оновленні документу. Запит не може бути опрацьований через конфлікт стану цільового ресурсу, наприклад, конфлікт одночасного редагування.
410
Архівовано. Шуканий ресурс не є й не буде доступним.
412
Збій під час обробки попередньої умови. Дивіться розділ Pобота з API в режимі кластеру.
422
Неможливо обробити об’єкт. Цей код стану означає, що сервер розуміє тип змісту об’єкта запиту. Наприклад, ця помилка може статися, якщо тіло запиту JSON містить добре сформовані (тобто синтаксично правильні), але семантично помилкові, інструкції у форматі JSON.
429
Перевищено допустиму частоту запитів. Дивіться розділ Контроль частоти запитів.
500
Помилка сервера. Була проблема зі сторони OpenProcurement.
501
Метод не підтримується. Сервер або не розпізнає метод запиту, або в нього немає можливості його виконати. Повторно перевірте відповідність запиту.
502
Помилка шлюзу. Сервер отримав відповідь про помилку чи не готовий обробляти запити. Для повторюваних операцій повторіть запит або перевіряйте дані об’єкту з інтервалом 1-5 хв.
503
Сервіс недоступний. На даний момент сервер недоступний (через перевантаження чи технічне обслуговування). Переважно ця помилка тимчасова.
504
Шлюз не відповідає. Сервер не дочекався відповіді. Для повторюваних операцій повторіть запит або перевіряйте дані об’єкту з інтервалом 1-5 хв.
505
Версія НТТР не підтримується. Сервер не підтримує версію протоколу HTTP, використану у запиті. Повторно перевірте відповідність запиту.

Відповідь з повідомленням про успіх

Кожен успішний запит вичитки, створення, оновлення, чи заміни отримує відповідь, що містить data атрибут. Цей data атрибут містить повне представлення JSON об’єкта після операції. Якщо деякі дані були згенеровані у результаті обробки (наприклад, нові ID об’єкта або modified дата), то вони присутні у відповіді.

Запити списку отримують схожі відповіді, але замість одного об’єкта в data атрибуті, JSON відповідь містить колекцію об’єктів.

Приклад відповіді з повідомленням про успіх

Це відповідь, що описує закупівлю.

HTTP/1.1 200 OK

{
    "data":{
        "id": "64e93250be76435397e8c992ed4214d1",
        "tenderID": "UA-2014-DUS-156",
        "dateModified": "2014-10-27T08:06:58.158Z",
        "procuringEntity": {
            "name": "ДУС"б
            "identifier": {
                "name": "Державне управління справами",
                "scheme": "UA-EDR",
                "uid": "00037256"
            },
            "address": {
                "countryName": "Україна",
                "postalCode": "01220",
                "region": "м. Київ",
                "locality": "м. Київ",
                "streetAddress": "вул. Банкова, 11, корпус 1"
            }
        },
        "value": {
            "amount": 500,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        },
        "items": [
            {
                "description": "футляри до державних нагород",
                "classification": {
                    "scheme": "CPV",
                    "id": "44617100-9",
                    "description": "Cartons"
                },
                "additionalClassifications": [
                    {
                        "scheme": "ДКПП",
                        "id": "17.21.1",
                        "description": "папір і картон гофровані, паперова й картонна тара"
                    }
                ],
                "quantity": 5,
                "unit": {
                    "name": "item"
                },
                "deliveryDate": {
                    "endDate": "2014-11-20T00:00:00"
                }
            }
        ],
        "clarificationPeriod": {
            "endDate": "2014-10-31T00:00:00"
        },
        "tenderPeriod": {
            "startDate": "2014-11-03T00:00:00",
            "endDate": "2014-11-06T10:00:00"
        },
        "minimalStep": {
            "amount": 35,
            "currency", "UAH",
            "valueAddedTaxIncluded": true
        }
    }
}

Відповідь з повідомленням про помилку

У випадку помилки, тіло відповіді міститиме errors поле на вищому рівні. Воно містить масив як мінімум одного помилкового об’єкта описаного нижче:

location:

Частина запиту спричинює помилку. Можливі значення це header (заголовок) або body (тіло).

name:
  • Конкретна назва заголовку, що спричиняє проблему (у випадку місцярозташування заголовок)
  • Конкретна назва поля, що спричиняє проблему (у випадку місцярозташування тіло)
description:

Докладний (придатний для читання людиною) опис помилки.

Приклад відповіді з повідомленням про помилку

Зразок нижче вказує на неповний запит.

HTTP/1.1 400 Missing input

{
  "status": "error",
  "errors": [
    {
      "location": "body",
      "name": "data",
      "description": "No JSON object could be decoded"
    }
  ]
}