Методы HTTP

Основной источник: RFC9110, Internet Engineering Task Force (IETF)

Токен метода запроса является основным источником семантики и указывает цель, с которой клиент сделал этот запрос, и то, что клиент ожидает в качестве успешного результата. Чувствителен к регистру.

+PATCH Method (описан как допка в RFC5789) для частичной модификации ресурсов. 


Все серверы общего назначения ДОЛЖНЫ поддерживать методы GET и HEAD. Все остальные методы НЕОБЯЗАТЕЛЬНЫ.

Набор методов, разрешенных целевым ресурсом, может быть указан в поле заголовка Allow.

Метод запроса, который не распознан или не реализован, ДОЛЖЕН ответить кодом состояния 501.

Метод запроса, который распознан и реализован, но не разрешен для целевого ресурса, ДОЛЖЕН ответить кодом состояния 405.


Свойства методов:

Безопасность. Методы запроса считаются «безопасными», если их определенная семантика по сути только для чтения; т. е. клиент не запрашивает и не ожидает никаких изменений состояния на исходном сервере в результате применения безопасного метода к целевому ресурсу. 

(!) Определение безопасного метода не препятствует реализации опасного поведения, однако важно то, что клиент не запрашивал это дополнительное поведение и не может нести за него ответственность. Например: безопасный запрос, инициированный выбором рекламы в Интернете, часто будет иметь побочный эффект в виде списания средств с рекламного счета.

Методы GET, HEAD, OPTIONS и TRACE определены как безопасные.

Владелец ресурса ДОЛЖЕН отключить или запретить опасное действие при доступе к нему с использованием безопасного метода запроса. Например "page?do=delete". Невыполнение этого требования приведет к нежелательным побочным эффектам, когда автоматизированные процессы выполняют GET для каждой ссылки URI для обслуживания ссылки, предварительной выборки, построения поискового индекса и т. д.

Целью различия безопасности - обеспечить возможность автоматизированных процессов поиска (пауков) и оптимизации производительности кэша (предварительной выборки) без опасения причинить вред. 

Идемпотентность. Метод запроса считается «идемпотентным», если предполагаемый эффект на сервере нескольких идентичных запросов с этим методом такой же, как эффект для одного такого запроса. 

Методы PUT, DELETE и безопасные (GET, HEAD, OPTIONS и TRACE) являются идемпотентными.

Как и определение безопасности, свойство идемпотентности применяется только к тому, что было запрошено пользователем. Сервер может отдельно реализовывать другие неидемпотентные побочные эффекты для каждого идемпотентного запроса.

Идемпотентный запрос может быть повторен и повторение запроса будет иметь тот же предполагаемый эффект. Клиент НЕ ДОЛЖЕН автоматически повторять запрос с неидемпотентным методом, если у него нет каких-либо средств узнать, что семантика запроса на самом деле идемпотентна.

Кеширование. RFC9110 определяет семантику кэширования для GET, HEAD и POST, хотя подавляющее большинство реализаций кэширования поддерживают только GET и HEAD. Чтобы кэш сохранял и использовал ответ, связанный метод должен явно разрешать кэширование и подробно описывать, при каких условиях ответ может использоваться для удовлетворения последующих запросов; определение метода, которое этого не делает, не может быть кэшировано.


GET

Метод GET запрашивает передачу текущего выбранного представления для целевого ресурса. GET — это основной механизм поиска информации и центр почти всех оптимизаций производительности.

Многие системы реализованы так, что GET представляет имена путей удаленной файловой системы и копии содержимого файлов в ответе. Однако это не единственная цель. GET может быть реализован как дерево объектов контента, программное представление различных записей базы данных или шлюз к другим информационным системам и т.д. Содержимое выдаваемого ресурса зависит от сервера.

Ответ на запрос GET можно кэшировать; кэш МОЖЕТ использовать его для удовлетворения последующих запросов GET и HEAD, если иное не указано в поле заголовка Cache-Control.


HEAD

Метод HEAD идентичен GET, за исключением того, что сервер НЕ ДОЛЖЕН отправлять содержимое в ответе. HEAD используется для получения метаданных о выбранном представлении без передачи данных его представления, часто для проверки гипертекстовых ссылок или поиска последних изменений.

Сервер ДОЛЖЕН отправлять те же поля заголовка в ответ на запрос HEAD, которые он отправил бы, если бы метод запроса был GET. Сервер МОЖЕТ опускать поля заголовка, для которых значение определяется только при генерации контента. Например: ответ на запрос GET может содержать поля Content-Length и Vary которые не генерируются в ответе HEAD.

Ответ на запрос HEAD кэшируется. Ответ HEAD может также повлиять на ранее кэшированные ответы на GET.


POST

Метод POST требует, чтобы целевой ресурс обрабатывал представление, заключенное в запросе, в соответствии с собственной специфической семантикой ресурса. 

Пример функций POST: предоставление блока данных (например полей, введенных в HTML-форме) процессу обработки данных, создание нового ресурса, который еще не идентифицирован исходным сервером, добавление данных к существующему представлению ресурса и т.д.

(!) Если в результате успешной обработки запроса POST на исходном сервере был создан один или несколько ресурсов, исходный сервер ДОЛЖЕН отправить ответ 201 (Created), содержащий поле заголовка Location , которое предоставляет идентификатор для созданного основного ресурса и представление, описывающее статус запроса при ссылке на новый ресурс.

Кэшированный ответ POST может быть повторно использован для удовлетворения более позднего запроса GET или HEAD. Напротив, запрос POST не может быть удовлетворен кэшированным ответом POST, поскольку POST потенциально небезопасен. Ответы на запросы POST кэшируются только в том случае, если они включают в себя явную информацию о свежести [CACHING] и поле заголовка Content-Location.

(!) Если результат обработки POST будет эквивалентен представлению существующего ресурса, исходный сервер МОЖЕТ перенаправить агента пользователя на этот ресурс, отправив ответ 303 (See Other).


PUT

Метод PUT запрашивает создание или замену состояния целевого ресурса на состояние, определенное представлением содержимого сообщения запроса. 

Успешный PUT предполагает, что последующий GET на том же целевом ресурсе приведет к отправке эквивалентного представления в ответе 200 (OK). Однако нет гарантии, что такое изменение состояния будет наблюдаемым, поскольку целевой ресурс может быть обработан другими.

(!) Если целевой ресурс не имеет текущего представления и PUT успешно его создает, то исходный сервер ДОЛЖЕН сообщить об этом пользовательскому агенту, отправив ответ 201 (Created). Если целевой ресурс имеет текущее представление и это представление успешно изменено, то исходный сервер ДОЛЖЕН отправить ответ 200 (OK) или 204 (No Content).

(!) Сервер ДОЛЖЕН проверить, что представление PUT соответствует целевому ресурсу. 
Если представление PUT не соответствует целевому ресурсу, сервер ДОЛЖЕН либо сделать их согласованными (перенастроить ресурс на новый тип данных или преобразовать сами данные PUTа), либо ответить соответствующим сообщением об ошибке. Предлагаются коды состояния 409 (Conflict) или 415 (Unsupported Media Type) (415 для ограничений Content-Type). 

Сервер ДОЛЖЕН игнорировать нераспознанные поля заголовка и трейлера, полученные в запросе PUT (т. е. не сохранять их как часть состояния ресурса).

Ответы на метод PUT не кэшируются. Сервер НЕ ДОЛЖЕН отправлять заголовки-валидаторы, такие как ETag или Last-Modified, в ответе на PUT, если он как-то изменил данные перед сохранением. Но если сервер сохранил данные без изменений, он может отправить эти заголовки, чтобы клиент знал, что его данные успешно записаны без модификаций и их не нужно снова извлекать с исходного сервера. 

Фундаментальное различие между методами POST и PUT заключается в том, что PUT определяется как замена состояния целевого ресурса и является идемпотентным. POST же предназначен для обработки вложенного в запрос представления (на основе семантики ресурса).


DELETE

Метод DELETE запрашивает у сервера удаление связи между целевым ресурсом и его текущей функциональностью. Метод похож на команду "rm" в UNIX: он выражает операцию удаления в сопоставлении URI сервера, а не ожидание того, что ранее связанная информация будет удалена.

Предполагается, что сервер разрешит DELETE только для ресурсов, для которых у него есть предписанный механизм для выполнения удаления. Например, реализация ресурса могут потребовать деактивации или архивации соединения с базой данных или шлюзом, уничтожения представления с восстановлением хранилища и т.д.

Если метод DELETE применен успешно, исходный сервер ДОЛЖЕН отправить:

  • код статуса 202 (Accepted), если действие, скорее всего, будет успешным, но еще не было выполнено
  • код статуса 204 (No Content), если действие было выполнено и дополнительная информация не предоставляется
  • код статуса  200 (OK), если действие было выполнено и ответное сообщение включает представление, описывающее статус

    • Клиент НЕ ДОЛЖЕН генерировать содержимое в запросе DELETE (если сервер ранее не указал, в пределах или за пределами диапазона, что такой запрос имеет цель и будет адекватно поддержан).

    Ответы на DELETE не кэшируются. Если успешный запрос DELETE проходит через кэш, в котором есть сохраненные ответы для целевого URI, эти сохраненные ответы будут аннулированы.


    CONNECT

    Метод CONNECT требует, чтобы получатель установил туннель к серверу-источнику назначения и, в случае успеха, затем ограничил свое поведение пересылкой данных в обоих направлениях, пока туннель не будет закрыт. Туннели обычно используются для создания сквозного виртуального соединения через один или несколько прокси, которое затем может быть защищено с помощью TLS (Transport Layer Security).

    CONNECT использует специальную форму цели запроса, уникальную для этого метода, состоящую только из хоста и номера порта назначения туннеля, разделенных двоеточием. Клиент ДОЛЖЕН отправить номер порта. Сервер ДОЛЖЕН отклонить запрос CONNECT, направленный на пустой или недействительный номер порта, обычно отвечая кодом состояния 400.

    CONNECT server.example.com:80 HTTP/1.1
    Host: server.example.com

    Ответы на метод CONNECT не кэшируются.


    OPTIONS

    Метод OPTIONS запрашивает информацию о доступных для целевого ресурса параметрах связи, как на исходном сервере, так и на промежуточном посреднике. Этот метод позволяет клиенту определить параметры и/или требования, связанные с ресурсом, или возможности сервера, не подразумевая действия ресурса.

    Сервер, генерирующий успешный ответ на OPTIONS, ДОЛЖЕН отправлять любой заголовок, который может указывать на дополнительные функции, реализованные сервером и применимые к целевому ресурсу (например, Allow), включая потенциальные расширения.

    Ответы на метод OPTIONS не кэшируются. 


    TRACE

    Метод TRACE запрашивает удаленный обратный цикл на уровне приложения для сообщения запроса. Получатель запроса ДОЛЖЕН отразить полученное сообщение в 200 (OK), за исключением некоторых полей.

    TRACE позволяет клиенту видеть, что принимается на другом конце цепочки запросов, и использовать эти данные для тестирования или диагностической информации. 

    Клиент НЕ ДОЛЖЕН отправлять контент в запросе TRACE. 

    Ответы на метод TRACE не кэшируются. 


    PATCH (RFC5789, IETF)

    Метод PATCH требует, чтобы набор изменений, описанных в запросе был применен к ресурсу, идентифицированному по URI. Разница между запросами PUT и PATCH отражена в способе, которым сервер должен обрабатывать вложенную сущность. В запросе PUT вложенная сущность считается измененной цельной версией ресурса. У PATCH вложенная сущность содержит набор инструкций, описывающих, как ресурс должен быть изменен для создания новой версии.

    Если Request-URI не указывают на существующий ресурс, сервер МОЖЕТ создать новый ресурс, в зависимости от типа документа исправления.

    PATCH не является ни безопасным, ни идемпотентным.

    Запрос PATCH может быть выдан таким образом, чтобы быть идемпотентным. Например, клиент может использовать сильный ETag в заголовке If-Match.

    (!) Сервер ДОЛЖЕН применить весь набор изменений. Если весь патч не может быть успешно применен, то сервер НЕ ДОЛЖЕН применять ни одно из изменений. 

    PATCH /file.txt HTTP/1.1
    Host: www.example.com
    Content-Type: application/example
    If-Match: "e0023aa4e
    Content-Length: 100
    [description of changes]


    Другие заметки

    ← К автору