HTTP. Краткие советы по использованию протокола
📌 URL идентифицирует ресурс. Вызов метода — не ресурс.
Не делайте так:
Лучше так:
Например, если у вас есть каталог котиков по породам, то породы — часть пути, города доставки — часть запроса, фрагмент – это якорь на странице:
📌 Методы GET, HEAD, OPTIONS — безопасные. Они не изменяют состояние ресурса. Некоторые сетевые агенты могут вызывать их без вашего согласия.
📌 Методы GET и HEAD кэшируются по умолчанию, остальные — нет. Если вы хотите шарахнуть по Луне методом GET, то можете получить ответ из кэша и не шарахнуть на самом деле.
📌 Методы GET, PUT, DELETE идемпотентны, то есть возвращают один и тот же результат. PUT кладёт ресурс по URL-у, GET возвращает его, DELETE удаляет его. Метод HEAD возвращает только заголовки ресурса.
📌 POST используется, если у вас нет URL для операции. Например, если вы создаёте новое сообщение на форуме и не можете самостоятельно сгенерировать его ID.
📌 Коды ответа нужны, чтобы клиент мог понять, что ему делать дальше.
3хх говорит, что нужно выполнить дополнительное действие.
4хх говорит, что клиент сделал что-то неправильно. В 4хх крайне рекомендуется включать информацию о том, что конкретно клиент сделал не так.
5хх говорит о том, что клиент всё сделал правильно — проблема на стороне сервера.
📌 Обычно при успешном выполнении операции сервер отвечает на GET — 200, на PUT — 201 Created (если ресурс создан) или 200 (ресурс обновлён), на DELETE — 204 (операция успешна, возвращать нечего), на POST — 200 или 201 (во втором случае в заголовке, обычно Location, указывается URL созданного ресурса).
📌 Работа с HTTP-статусами:
401 Unauthorized обязан сопровождаться заголовком WWW-Authenticate и подходит только для HTTP-аутентификации. Используйте 403 Forbidden для других случаев.
3xx статусы требуют дополнительного действия от клиента. Например, 304 Not Modified означает, что клиент должен взять ресурс из кэша.
404 статус может повторяться, так как ресурс может появиться позже. Если ресурса нет и не будет, используйте 410 Gone или 400.
📎 Материалы по теме
1. 15 тривиальных фактов о правильной работе с протоколом HTTP — Хабр, Яндекс
2. REST API Best Practices / Хабр
3. Best Practices in API Design — блог Swagger
📌 URL идентифицирует ресурс. Вызов метода — не ресурс.
Не делайте так:
GET /?method=шарахнуть&to=Луна Лучше так:
POST /шарахалка/?to=Луна
📌 URL состоит из схемы, хоста, пути, запроса и фрагмента. Путь — для иерархических ресурсов, запрос — для неиерархических и параметров операции. Фрагмент — для подчинённых ресурсов без URL.Например, если у вас есть каталог котиков по породам, то породы — часть пути, города доставки — часть запроса, фрагмент – это якорь на странице:
http://nyashnye-kotiki.xxx/breeds/maine-coon/?deliver_to=Moscow#photo📌 Обращение по HTTP — это применение метода (глагола) к URL. Результат должен соответствовать глаголу. Например, GET возвращает ресурс, DELETE удаляет его.
📌 Методы GET, HEAD, OPTIONS — безопасные. Они не изменяют состояние ресурса. Некоторые сетевые агенты могут вызывать их без вашего согласия.
📌 Методы GET и HEAD кэшируются по умолчанию, остальные — нет. Если вы хотите шарахнуть по Луне методом GET, то можете получить ответ из кэша и не шарахнуть на самом деле.
📌 Методы GET, PUT, DELETE идемпотентны, то есть возвращают один и тот же результат. PUT кладёт ресурс по URL-у, GET возвращает его, DELETE удаляет его. Метод HEAD возвращает только заголовки ресурса.
📌 POST используется, если у вас нет URL для операции. Например, если вы создаёте новое сообщение на форуме и не можете самостоятельно сгенерировать его ID.
POST /threads/php-rulezz/messagesЕсли вы повторите POST запрос — создастся дубликат сообщения. PUT можно повторять сколько угодно — результат не изменится. Это свойство называется идемпотентностью. Если клиент сам может сгенерировать ID, лучше использовать PUT:
PUT /threads/php-rulezz/messages/100500📌 PUT может создавать или обновлять ресурсы целиком. PATCH может модифицировать ресурсы частично.
📌 Коды ответа нужны, чтобы клиент мог понять, что ему делать дальше.
3хх говорит, что нужно выполнить дополнительное действие.
4хх говорит, что клиент сделал что-то неправильно. В 4хх крайне рекомендуется включать информацию о том, что конкретно клиент сделал не так.
5хх говорит о том, что клиент всё сделал правильно — проблема на стороне сервера.
📌 Обычно при успешном выполнении операции сервер отвечает на GET — 200, на PUT — 201 Created (если ресурс создан) или 200 (ресурс обновлён), на DELETE — 204 (операция успешна, возвращать нечего), на POST — 200 или 201 (во втором случае в заголовке, обычно Location, указывается URL созданного ресурса).
📌 Работа с HTTP-статусами:
401 Unauthorized обязан сопровождаться заголовком WWW-Authenticate и подходит только для HTTP-аутентификации. Используйте 403 Forbidden для других случаев.
3xx статусы требуют дополнительного действия от клиента. Например, 304 Not Modified означает, что клиент должен взять ресурс из кэша.
404 статус может повторяться, так как ресурс может появиться позже. Если ресурса нет и не будет, используйте 410 Gone или 400.
📎 Материалы по теме
1. 15 тривиальных фактов о правильной работе с протоколом HTTP — Хабр, Яндекс
2. REST API Best Practices / Хабр
3. Best Practices in API Design — блог Swagger