Http методи для створення restful сервісів

HTTP дієслова становлять основну частину "єдиного інтерфейсу", який би і надає можливість здійснювати дії над іменником-ресурсом. Основними або найбільш часто використовуваними HTTP дієсловами (або методами, як їх іноді називають) є POST, GET, PUT, і DELETE. Вони відповідають операціям створення, читання, оновлення та видалення (або в сукупності - CRUD). Є ще й інші дієслова, але вони використовуються рідше. З рідше використовуваних методів виділяються OPTIONS і HEAD

Нижче наведена зведена таблиця рекомендацій по поверненню значень при використанні основних HTTP дієслів в поєднанні з ресурсами URI:

Ресурс (наприклад / customers)

Примірник (наприклад / customers /)

200 (OK), перелік customers. Використовується посторінкова навігація, сортування і фільтрація для великих списків.

200 (OK), конкретний customer. 404 (Not Found), в разі відсутності примірника із зазначеним ID або якщо він не коректний (а також, якщо клієнту не дозволено знати про наявність даного екземпляра).

404 (Not Found), якщо була спроба оновити / замінити екземпляр у всій колекції.

200 (OK) або 204 (No Content). 404 (Not Found), в разі відсутності примірника із зазначеним ID або якщо він не коректний (а також, якщо клієнту не дозволено знати про наявність даного екземпляра).

201 (Created), заголовок 'Location' посилається на / customers /, де ID - ідентифікатор нового екземпляра.

404 (Not Found), якщо ви хочете видалити вс колекцію, що вкрай не бажано.

Нижче наводиться більш докладне обговорення основних методів HTTP. Використовуйте навігацію по вкладках для отримання додаткових відомостей про інтересуемом HTTP методі.

У відповідність технічним умовам HTTP, GET (також як і HEAD) запити використовуються тільки для читання даних, що не змінять їх. Таким чином, при дотриманні даної угоди, вони вважаються безпечними. Тобто вони можуть використовуватися без ризику зміни даних, незалежно від того, один раз дані були отримані, або ж 10, або жодного разу зовсім. GET (а також HEAD) запити є Ідемпотентний (тотожними), що має на увазі отримання ідеінтічних даних при використанні одних і теж же запитів (як при одиничному зверненні, так і при багаторазовому).

Не варто використовувати GET для небезпечних операцій над даними, при цьому запиті вони не повинні бути модифіковані.

Метод PUT зазвичай використовується для надання можливості поновлення ресурсу. Тіло запиту при відправленні PUT-запиту до існуючого ресурсу URI має містити оновлені дані оригінального ресурсу (повністю, або тільки оновлювану частина).

Для створення нових екземплярів ресурсу краще іспользозваніе POST запиту. В даному випадку, при створенні екземпляра буде надано коректний ідентфікатор примірника ресурсу в повернутих даних про екземпляр.

При успішному оновленні за допомогою виконання PUT запиту повертається код 200 (або 204 якщо не був переданий будь-якої контент в тілі відповіді). Якщо PUT використовується для створення екземпляра - зазвичай повертають HTTP код 201 при успішному створенні. Повертати дані у відповідь на запит не обов'язково. Також не обов'язково повертати посилання на екземпляр ресурсу за допомогою заголовка `Location` через те, що клієнт і так володіє ідентифікатором екземпляра ресурсу.

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

POST запит найбільш часто використовується для створення нових ресурсів. На практиці він використовується для створення вкладених ресурсів. Іншими словами, при створенні нового ресурсу, POST запит відправляється до батьківського ресурсу і, таким чином, сервіс бере на себе відповідальність на встановлення зв'язку створюваного ресурсу з батьківським ресурсом, призначення нового ресурсу ID і т.п.

POST не є безпечним або ідемпотентна запитом. Тому рекомендується його використання для НЕ ідемпотентна запитів. В результаті виконання ідентичних POST запитів надаються сильно схожі, але не ідеінтічние дані.

DELETE запит вкрай простий для розуміння. Він використовується для видалення ресурсу, ідентифікованого конкретним URI (ID).

При успішному видаленні повертається 200 (OK) код HTTP, спільно з тілом відповіді, содаржащім дані віддаленого ресурсу (негативно позначається на економії трафіку) або загорнуті відповіді (Дивіться "повертаються дані"). Також можливе використання HTTP коду 204 (NO CONTENT) без тіла відповіді.

Згідно зі специфікацією HTTP, DELETE запит ідемпотентів. Якщо ви виконуєте DELETE запит до ресурсу, він видаляється. Повторний DELETE запит до ресурсу закінчиться також: ресурс видалений. Якщо DELETE запит використовується для декремента лічильника, DELETE запит не є ідемпотентна. Використовуйте POST для НЕ ідемпотентів операцій.

Проте, існує застереження про ідемпотентності DELETE. Повторний DELETE запит до ресурсу часто супроводжується 404 (NOT FOUND) кодом HTTP через те, що ресурс вже видалений (наприклад з бази даних) і більш не доступний. Це робить DELETE операція не Ідемпотентний, але це загальноприйнятий компроміс на той випадок, якщо ресурс був вилучений з бази даних, а не позначений, як віддалений.