Коди відповідей REST API

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

Взагалі HTTP визначає 40 стандартних кодів стану (статусів відповіді), які поділяються на п’ять категорій. Нижче виділено лише коди стану, які часто використовуються в REST API.

КатегоріяОпис
1xx: ІнформаціяУ цей клас містить заголовки, що інформують про процес передачі. Це зазвичай попередня відповідь, що складається тільки з Status-Line та опціональних заголовків, і завершується порожнім рядком. Немає обов’язкових заголовків. Сервери НЕ ПОВИННІ надсилати 1xx відповіді HTTP/1.0 клієнтам.
2xx: УспіхЦей клас кодів стану вказує, що запит клієнта був успішно отриманий, зрозумілий та прийнятий.
3xx: ПеренаправленняКоди цього класу повідомляють клієнту, що з успішного виконання операції необхідно зробити інший запит, зазвичай, інакше URI. З цього класу п’ять кодів 301, 302, 303, 305 та 307 відносяться безпосередньо до перенаправлень.
4xx: Помилка клієнтаКлас кодів 4xx призначений для вказівки помилок клієнта.
5xx: Помилка сервераКоди відповідей, що починаються з “5”, вказують на випадки, коли сервер знає, що виникла помилка або він не може обробити запит.

Коди станів у REST

Зірочкою *– позначені найчастіше використовувані коди відповідей.




200*(OK)

Запит виконано успішно. Інформація, що повертається з відповіддю, залежить від методу, який використовується у запиті, наприклад:

  • GET Отримано об’єкт, який відповідає запрошеному ресурсу.
  • HEAD Отримано поля заголовків, які відповідають запитаному ресурсу, тіло відповіді порожнє.
  • POST Запропонована дія виконана.




201* (Created – Створено)

REST API відповідає коду стану 201 при кожному створенні ресурсу в колекції. Також можуть бути випадки, коли новий ресурс створюється внаслідок будь-якої дії контролера, і в цьому випадку 201 також буде відповідною відповіддю.

Посилання (URL) на новий ресурс може бути в тілі відповіді або поле заголовка відповіді Location.

Сервер повинен створити ресурс перед тим, як повернути 201 статус. Якщо це неможливо зробити відразу, сервер повинен відповісти кодом 202 (Accepted).




202 (Accepted – Прийнято)

Відповідь 202 зазвичай використовується для дій, які займають багато часу для обробки та не можуть бути виконані відразу. Це означає, що запит прийнято до обробки, але обробка не завершена.

Його мета полягає в тому, щоб дозволити серверу прийняти запит на будь-який інший процес (можливо пакетний процес, який виконується тільки один раз на день), не вимагаючи, щоб з’єднання агента користувача з сервером зберігалося до тих пір, поки процес не буде завершено.

Сутність, що повертається з цією відповіддю, повинна містити вказівку на поточний стан запиту та вказівник на монітор стану (розташування черги завдань) або деяку оцінку того, коли користувач може очікувати на виконання запиту.




203 (Non-Authoritative Information – Неавторитетна інформація)

Надана інформація взята не з оригінального джерела (а, наприклад, з кешу, який міг застаріти, або резервної копії, яка могла втратити актуальність). Цей факт відображено у заголовку відповіді та підтверджується цим кодом. Надана інформація може збігатися, а може і не збігатися з оригінальними даними.




204 * (No Content – Немає контенту)

Код стану 204 зазвичай відправляється у відповідь на запит PUT, POST або DELETE, коли REST API відмовляється відправляти будь-яке повідомлення про стан виконаної роботи.

API може також надіслати 204 статус у відповідь на GET запит, щоб вказати, що запитаний ресурс існує, але не має даних, щоб додати їх у тіло відповіді.

Відповідь 204 не повинна містити тіло повідомлення і таким чином завжди завершується першим порожнім рядком після полів заголовка.




205 – (Reset Content – Скинутий вміст)

Сервер успішно обробив запит та зобов’язує клієнта скинути введені користувачем дані. У відповіді не повинно передаватись жодних даних (у тілі відповіді). Зазвичай застосовується повернення у початковий стан форми введення даних клієнта.




206 – (Partial Content – Частковий вміст)

Сервер виконав частину GET запиту ресурсу. Запит ПОВИНЕН був містити поле заголовка Range (секція 14.35), який вказує на бажаний діапазон і МОГ містити поле заголовка If-Range (секція 14.27), який робить умовним запит.

Запит ПОВИНЕН містити такі поля заголовка:

  • Або поле Content-Range (секція 14.16), який показує діапазон, включений у цей запит, або Content-Type зі значенням multipart/byteranges, що включають поля Content-Range для кожної частини. Якщо в заголовку запиту є поле Content-Length, його значення ПОВИННО співпадати з фактичною кількістю октетів, переданих у тілі повідомлення.
  • Date
  • ETag та/або Content-Location, якщо раніше була отримана відповідь 200 на такий самий запит.
  • Expires, Cache-Control та/або Vary, якщо значення поля змінилося з моменту відправлення останнього такого ж запиту

Якщо відповідь 206 – це результат виконання умовного запиту, який використовував строгий кеш-валідатор (докладніше у секції 13.3.3), у відповідь НЕ СЛІД включати будь-які інші заголовки сутності. Якщо така відповідь – результат виконання запиту If-Range, який використовував “слабкий” валідатор, то відповідь НЕ ПОВИНЕН містити інші заголовки сутності; це запобігає невідповідності між закешованими тілами сутностей та оновленими заголовками. В іншому випадку відповідь ПОВИНЕН містити всі заголовки сутностей, які повернули статус 200 (OK) на той самий запит.

Кеш НЕ ПОВИНЕН поєднувати відповідь 206 з іншими раніше закешованими даними, якщо поле ETag або Last-Modified точно не збігаються (докладніше у секції 16.5.4)

Кеш, який не підтримує заголовки Range та Content-Range НЕ ПОВИНЕН кешувати відповіді 206 (Partial).




300 – (Multiple Choices – Кілька варіантів)

За вказаним URI існує кілька варіантів надання ресурсу за типом MIME, за мовою чи іншими характеристиками. Сервер передає із повідомленням список альтернатив, даючи можливість зробити вибір клієнту автоматично або користувачеві.

Якщо це не запит HEAD, відповідь ПОВИНЕН включати об’єкт, що містить список характеристик та адрес, з якого користувач або агент користувача може вибрати один, що найбільше підходить. Формат об’єкта визначається за типом даних, наведених у Content-Type поля заголовка. Залежно від формату та можливостей агента користувача, вибір найбільш відповідного варіанта може виконуватися автоматично. Однак ця специфікація не визначає жодного стандарту автоматичного вибору.

Якщо сервер має кращий вибір представлення, він повинен включити конкретний URI для цього представлення в полі Location; Агент користувача МОЖЕ використовувати заголовок Location для автоматичного перенаправлення до запропонованого ресурсу. Цей запит може бути закешований, якщо не було вказано іншого.




301 (Moved Permanently – Переміщено назавжди)

Код перенаправлення. Вказує, що модель ресурсів REST API була дуже змінена і тепер має новий URL. Rest API повинен вказати новий URI у заголовку відповіді Location, і всі майбутні запити мають бути спрямовані на зазначений URI.

Ви навряд чи будете використовувати цей код відповіді у своєму API, тому що ви завжди можете використовувати версію API для нового API, зберігаючи при цьому старий.




302 (Found – Знайдено)

Є поширеним способом виконати перенаправлення на іншу URL-адресу. HTTP-відповідь з цим кодом має додатково надати URL-адресу, куди перенаправляти в поле заголовка Location. Агенту користувача (наприклад, браузеру) пропонується у відповіді з цим кодом зробити другий запит на новий URL.

Багато браузерів реалізували цей код таким чином, що порушили стандарт. Вони почали змінювати Тип вихідного запиту, наприклад, з POST на GET. Коди стану 303 та 307 були додані для серверів, які хочуть однозначно визначити, яка реакція очікується від клієнта.




303 (See Other – Дивіться інше)

Відповідь 303 вказує, що ресурс контролера завершив свою роботу, але замість надсилання небажаного тіла відповіді він надсилає клієнту URI ресурсу. Це може бути URI тимчасового повідомлення про стан ресурсу або URI для існуючого постійного ресурсу.

Код стану 303 дозволяє REST API вказати посилання ресурс, не змушуючи клієнта завантажувати відповідь. Натомість клієнт може відправити GET запит на URL вказаний у заголовку Location.

Відповідь 303 не повинна кешуватися, але відповідь на другий (перенаправлений) запит може бути кешується.




304 * (Not Modified – Не змінено)

Цей код стану схожий на 204 (Немає контенту), оскільки тіло відповіді має бути порожнім. Ключова відмінність полягає в тому, що 204 використовується, коли немає нічого для відправки в тілі, тоді як 304 використовується, коли ресурс не був змінений з версії, вказаної заголовками запиту If-Modified-Sinceабо If-None-Match.

У такому разі немає потреби повторно передавати ресурс, оскільки у клієнта досі є раніше завантажена копія.

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




305 – (Use Proxy – Використовуйте проксі)

Доступ до запитаного ресурсу ПОВИНЕН бути здійснений через проксі-сервер, вказаний у полі Location. Поле Location надає проксі URI. Очікується, що одержувач повторить запит за допомогою проксі. Відповідь 305 може генеруватися ТІЛЬКИ серверами-джерелами.

Зауважте: у специфікації RFC 2068 однозначно не сказано, що відповідь 305 призначена для перенаправлення єдиного запиту, і що вона повинна генеруватися тільки сервером-джерелом. Упущення цих обмежень викликало низку значних наслідків безпеки.

Багато HTTP клієнтів (такі, як Mozilla та Internet Explorer) обробляють цей статус некоректно насамперед із міркувань безпеки.




307 (Temporary Redirect – Тимчасовий редирект)

Відповідь 307 вказує, що rest API не оброблятиме запит клієнта. Натомість клієнт повинен повторно надіслати запит на URL, вказаний у заголовку Location. Однак у майбутніх запитах клієнт, як і раніше, повинен використовувати вихідну URL-адресу.

Rest API може використовувати цей код стану для призначення тимчасового URL запитуваному ресурсу.

Якщо метод запиту не HEAD, тіло відповіді має містити коротку замітку з посиланням на новий URL. Якщо код 307 був отриманий у відповідь на запит, відмінний від GET або HEAD, Клієнт не повинен автоматично перенаправляти запит, якщо він не може бути підтверджений Клієнтом, оскільки це може змінити умови, за яких було створено запит.




308 – (Permanent Redirect – Постійне перенаправлення) (experimental)

Потрібно повторити запит на іншу адресу без зміни методу.

Цей і всі наступні запити слід повторити на інший URI. 307 та 308 (як запропоновано) Схожий у поведінці з 302 та 301, але не вимагають заміни HTTP методу. Таким чином, наприклад, відправлення форми на “постійно перенаправлений” ресурс можна без проблем.




400* (Bad Request – Поганий запит)

Це загальний статус помилки на стороні Клієнта. Використовується, коли інший код помилки 4xx не доречний. Помилки можуть бути як неправильний синтаксис запиту, неправильні параметри запиту, запити, що вводять в оману або маршрутизатор і т.д.

Клієнт не повинен повторювати такий самий запит.




401 * (Unauthorized – Неавторизований)

401 повідомлення про помилку вказує, що клієнт намагається працювати із закритим ресурсом без надання даних авторизації. Можливо, він надав неправильні облікові дані чи взагалі нічого. Відповідь має містити поле заголовка WWW-Authenticate, що містить опис проблеми.

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




402 – (Payment Required – Потрібна оплата)

Цей код зарезервований для використання у майбутньому.

Передбачається використовувати у майбутньому. На даний момент не використовується. Цей код передбачений для платних сервісів, а не для хостингових компаній. Мається на увазі, що цю помилку не буде видано хостинговим провайдером у разі простроченої оплати його послуг. Зарезервований починаючи з HTTP/1.1.




403* (Forbidden – Заборонено)

Помилка 403 показує, що rest API відмовляється виконувати запит клієнта, тобто. Клієнт не має необхідних дозволів на доступ. Відповідь 403 не є нагодою, коли потрібна авторизація (для помилки авторизації використовується код 401).

Спроба автентифікації не допоможе, і повторні запити не мають сенсу.




404* (Not Found – Не знайдено)

Вказує, що rest API не може порівняти URL клієнта з ресурсом, але цей URL може бути доступним у майбутньому. Наступні запити клієнта допустимі.

404 не вказує, чи стан тимчасовим або постійним. Для постійного стану використовується код 410 (Gone – Пропал) . 410 використовуватись, якщо сервер знає, що старий ресурс постійно недоступний і більше не має адреси.




405 (Method Not Allowed – Метод не дозволено)

API видає помилку 405, коли клієнт намагався використовувати метод HTTP, який неприпустимий для ресурсу. Наприклад, зазначений метод PUT, але такого методу ресурс не має.

Відповідь 405 повинен включати Заголовок Allow, в якому перераховані методи, що підтримуються HTTP, наприклад, Allow: GET, POST.




406 (Not Acceptable – Неприйнятний)

API не може генерувати типи даних, які вказані в заголовку запиту Accept. Наприклад, запит клієнта на дані у форматі application/xmlотримає відповідь 406, якщо API вміє віддавати дані лише у форматі application/json.

У таких випадках Клієнт повинен вирішити проблему даних у себе і лише потім надсилати запити повторно.




407 – (Proxy Authentication Required – Потрібна проксі-автентифікація)

Відповідь аналогічна коду 401, за винятком того, що аутентифікація проводиться для проксі-сервера. Механізм подібний до ідентифікації на вихідному сервері.

Користувач повинен спочатку авторизуватися через проксі. Проксі-сервер повинен повернути заголовок Proxy-Authenticate, що містить запит ресурсу. Клієнт може повторити запит разом із Proxy-Authenticate заголовком. З’явився у HTTP/1.1.




408 – (Request Timeout – Таймаут запиту)

Час очікування сервером передачі від клієнта минув. Клієнт не надав запит за час, поки сервер був готовий його прийнято. Клієнт може повторити запит без змін у будь-який час.

Наприклад, така ситуація може виникнути під час завантаження на сервер об’ємного файлу методом POST або PUT. У якийсь момент передачі джерело даних перестало відповідати, наприклад, через пошкодження компакт-диска або втрату зв’язку з іншим комп’ютером у локальній мережі. Поки клієнт нічого не передає, очікуючи відповіді, з’єднання з сервером тримається. Через деякий час сервер може закрити з’єднання зі свого боку, щоб надати можливість іншим клієнтам зробити запит.




409* (Conflict – Конфлікт)

Запит не можна опрацювати через конфлікт у поточному стані ресурсу. Цей код дозволяється використовувати лише у випадках, коли очікується, що користувач може самостійно вирішити цей конфлікт та повторити запит. У тіло відповіді слід включити достатню кількість інформації для того, щоб користувач зміг зрозуміти причину конфлікту. В ідеалі відповідь має містити таку інформацію, яка допоможе користувачеві чи його агенту виправити проблему. Однак це не завжди можливе і це не обов’язково.

Як правило, конфлікти відбуваються під час PUT-запиту. Наприклад, під час використання версіонування, якщо сутність, до якої звертаються методом PUT, містить зміни, що конфліктують з тими, що були зроблені раніше третьою стороною, сервер повинен використовувати відповідь 409, щоб дати зрозуміти користувачеві, що цей запит не можна завершити. У цьому випадку сутність у відповідь має містити список змін між двома версіями у форматі, який вказаний у полі заголовка Content-Type.




412 (Precondition Failed – Передумова провалено)

Коли клієнт вказує rest API виконувати запит лише за виконання певних умов, а API не може виконати запит за таких умов, то повертається відповідь 412.




410 – (Gone – Зник)

Така відповідь сервер посилає, якщо ресурс раніше був за вказаною URL-адресою, але був видалений і тепер недоступний. Серверу в цьому випадку невідоме місце розташування альтернативного документа, наприклад, копії. Якщо сервер має підозру, що документ найближчим часом може бути відновлений, то краще клієнту передати код 404. З’явився в HTTP/1.1.




411 – (Length Required – Потрібна довжина)

Для зазначеного ресурсу клієнт має вказати Content-Length у заголовку запиту. Без вказівки цього поля не слід робити повторну спробу запиту до сервера за цим URI. Така відповідь є природною для запитів типу POST і PUT. Наприклад, якщо за вказаним URI здійснюється завантаження файлів, а сервер має обмеження з їхньої обсяг. Тоді розумніше перевірити на самому початку заголовок Content-Length і відразу відмовити в завантаженні, ніж провокувати безглузде навантаження, розриваючи з’єднання, коли клієнт дійсно надішле надто об’ємне повідомлення.




412 – (Precondition Failed – Попередня умова не виконана)

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

Цей код відповіді дозволяє клієнту записувати попередні умови в метаінформації поточного ресурсу, таким чином запобігаючи застосуванню запитаного методу до ресурсу, крім того, що очікується.




413 – (Request Entity Too Large – Сутність запиту занадто велика)

Повертається у випадку, якщо сервер відмовляється обробити запит через занадто великий розмір запиту. Сервер може закрити з’єднання, щоб припинити передачу запиту.

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




414 – (Request-URI Too Long – Запит-URI Занадто довгий)

Сервер не може обробити запит через надто довгу вказану URL-адресу. Цю рідкісну помилку можна спровокувати, наприклад, коли клієнт намагається передати довгі параметри через метод GET, а не POST, коли клієнт потрапляє в “чорну дірку” перенаправлень (наприклад, коли префікс URI вказує на своє закінчення), або коли сервер піддається атаці з сторони клієнта, який намагається використовувати діри в безпеці, які зустрічаються на серверах з фіксованою довжиною буфера для читання або обробки Request-URI.




415 (Unsupported Media Type – Непідтримуваний тип медіа)

Повідомлення про помилку 415 вказує, що API не може обробити наданий клієнтом Тип медіа, як зазначено у заголовку запиту Content-Type.

Наприклад, запит клієнта містить дані у форматі application/xml, а API готовий обробити лише application/json. І тут клієнт отримає відповідь 415.

Наприклад, клієнт завантажує зображення як image/svg+xml, але сервер вимагає, щоб зображення використовували інший формат.




428 – (Precondition Required – Потрібна попередня умова)

Код стану 428 вказує на те, що вихідний сервер вимагає, щоб запит був умовним.

Його типове використання — уникнути проблеми «втраченого оновлення», коли клієнт ОТРИМАЄ стан ресурсу, змінює його та відправляє назад на сервер, коли тим часом третя сторона змінила стан на сервері, що призвело до конфлікту. Вимагаючи, щоб запити були умовними, сервер може гарантувати, що клієнти працюють із правильними копіями.

Відповіді з цим кодом стану ПОВИННІ пояснювати, як повторно надіслати запит.




429 – (Too Many Requests – Занадто багато запитів)

Користувач надіслав багато запитів за заданий проміжок часу.

Подання відповіді ПОВИННІ включати подробиці, що пояснюють умову, і МОЖУТЬ включати заголовок Retry-After, що вказує, як довго чекати, перш ніж робити новий запит.




431 – (Request Header Fields Too Large – Занадто великі поля заголовка запиту)

Код стану 431 вказує на те, що сервер не бажає обробляти запит, оскільки його поля заголовка дуже великі. Запит МОЖЕ бути відправлений після зменшення розміру полів заголовка запиту.

Його можна використовувати як у випадку, коли сукупність полів заголовка запиту дуже велика, так і у разі несправності одного поля заголовка. У разі подання відповіді ПОВИННО вказувати, яке поле заголовка було занадто великим.




444 – (No Response – Немає відповіді) (Nginx)

Код відповіді Nginx. Сервер не повернув інформацію та закрив з’єднання. (корисно як стримуючий фактор для шкідливих програм)




451 – (Unavailable For Legal Reasons – Недоступний з юридичних причин)

Доступ до ресурсу закрито з юридичних причин. Найбільш близьким із існуючих є код 403 Forbidden (сервер зрозумів запит, але відмовляється його обробити). Однак у разі цензури, особливо коли ця вимога до провайдерів заблокувати доступ до сайту, сервер ніяк не міг зрозуміти запиту — він його навіть не отримав. Точно підходить інший код: 305 Use Proxy. Однак таке використання цього коду може не сподобатися цензорам. Було запропоновано кілька варіантів для нового коду, включаючи “112 Emergency. Censorship in action” та “460 Blocked by Repressive Regime”




500* (Internal Server Error – Внутрішня помилка сервера)

Загальна відповідь при помилці коду. Універсальне повідомлення про внутрішню помилку сервера, коли ніяке певне повідомлення не підходить.

Більшість веб-платформ автоматично відповідають цим кодом стану, коли під час виконання коду обробника запиту виникла помилка.

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




501 (Not Implemented – Не реалізовано)

Сервер або невідомий метод запиту, або йому (сервер) не вистачає можливостей виконати запит. Зазвичай це має на увазі майбутню доступність (наприклад, нова функція API веб-сервісу).

Якщо ж метод серверу відомий, але він не застосовний до даного ресурсу, потрібно повернути відповідь 405.




502 – (Bad Gateway – Поганий шлюз)

Сервер, виступаючи в ролі шлюзу або проксі-сервера, отримав некоректну відповідь від сервера, до якого він звернувся. З’явився у HTTP/1.0.




503 – (Service Unavailable – Служба недоступна)

Сервер не може обробити запит через тимчасове навантаження або технічні роботи. Це тимчасовий стан, з якого сервер вийде через якийсь час. Якщо цей час відомий, то його МОЖНА передати в заголовку Retry-After.




504 – (Gateway Timeout – Таймаут шлюзу)

Сервер, у ролі шлюзу чи проксі-сервера, не дочекався у межах встановленого таймууту відповіді вищого сервера поточного запиту.




505 – (HTTP Version Not Supported – Версія HTTP не підтримується)

Сервер не підтримує або відмовляється підтримувати версію протоколу HTTP, вказану в запиті.




510 – (Not Extended – Не розширено)

У запиті не дотримано політику доступу до ресурсу. Сервер повинен надіслати назад всю інформацію, необхідну клієнту для надсилання розширеного запиту. Вказівка ​​того, як розширення інформують клієнта, виходить за межі цієї специфікації.

Джерела та більш детальна інформація:

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *