POST означает «создать новый», как в «Вот ввод для создания пользователя, создайте его для меня».

PUT означает «вставить, заменить, если уже существует», как в «Вот данные для пользователя 5».

Вы POST на example.com/users, поскольку вы еще не знаете URL пользователя, вы хотите, чтобы сервер создал его.

Вы PUT на example.com/users/id, поскольку хотите заменить / создать конкретного пользователя.

Публикация дважды с одними и теми же данными означает создание двух одинаковых пользователей с разными идентификаторами. Если дважды вставить одни и те же данные, пользователь будет первым, а второй раз обновит его до того же состояния (без изменений). Поскольку вы в конечном итоге получаете одно и то же состояние после PUT, независимо от того, сколько раз вы его выполняете, он каждый раз считается «одинаково мощным» - идемпотентным. Это полезно для автоматического повторения запросов. Больше никаких «вы уверены, что хотите отправить повторно?», Когда вы нажимаете кнопку «Назад» в браузере.

Общий совет - использовать POST, когда вам нужно, чтобы сервер контролировал URL создание ваших ресурсов. В противном случае используйте PUT. Предпочитайте PUT, а не POST.

Хочу добавить свой «прагматический» совет. Используйте PUT, если знаете "id", по которому можно получить сохраняемый объект. Использование PUT не будет работать слишком хорошо, если вам, скажем, нужно, чтобы идентификатор, сгенерированный базой данных, возвращался вам для выполнения будущих поисков или обновлений.

Итак: чтобы сохранить существующего пользователя или того, у которого клиент генерирует идентификатор, и было подтверждено, что идентификатор уникален:

PUT /user/12345 HTTP/1.1  <-- create the user providing the id 12345
Host: mydomain.com

GET /user/12345 HTTP/1.1  <-- return that user
Host: mydomain.com

В противном случае используйте POST для первоначального создания объекта и PUT для обновления объекта:

POST /user HTTP/1.1   <--- create the user, server returns 12345
Host: mydomain.com

PUT /user/12345 HTTP/1.1  <--- update the user
Host: mydomain.com

Оба используются для передачи данных между клиентом и сервером, но между ними есть тонкие различия, а именно:

Аналогия:

• PUT, т.е. взять и положить на место.
• ОТПРАВИТЬ как отправить письмо в почтовое отделение.

Социальные сети / аналогия с сетью:

• Публикация в социальных сетях: когда мы публикуем сообщение, создается новое сообщение.
• Поместите (т. е. отредактируйте) для уже отправленного сообщения.

Используйте POST для создания и PUT для обновления. Во всяком случае, именно так это делает Ruby on Rails.

PUT    /items/1      #=> update
POST   /items        #=> create

REST - это концепция очень высокого уровня. Фактически, он даже не упоминает HTTP!

Если у вас есть сомнения по поводу реализации REST в HTTP, вы всегда можете взглянуть на публикацию Atom Спецификация протокола (AtomPub). AtomPub - это стандарт для написания веб-сервисов RESTful с HTTP, который был разработан многими светилами HTTP и REST при участии Роя Филдинга, изобретателя REST и (со) изобретателя HTTP.

Фактически, вы даже можете напрямую использовать AtomPub. Хотя он вышел из сообщества блоггеров, он никоим образом не ограничивается ведением блогов: это общий протокол для RESTful-взаимодействия с произвольными (вложенными) коллекциями произвольных ресурсов через HTTP. Если вы можете представить свое приложение как вложенную коллекцию ресурсов, вы можете просто использовать AtomPub и не беспокоиться о том, использовать ли PUT или POST, какие коды состояния HTTP возвращать и все эти детали.

Вот что AtomPub говорит о создании ресурсов (раздел 9.2):

Чтобы добавить членов в Коллекцию, клиенты отправляют запросы POST на URI Коллекции.

Решение о том, использовать ли PUT или POST для создания ресурса на сервере с HTTP + REST API, зависит от того, кому принадлежит структура URL. Наличие у клиента информации или участия в определении URL struct - это ненужная связь, подобная нежелательной связи, возникшей из SOA. Избегание типов муфт - причина такой популярности REST. Поэтому правильным методом для использования является POST. Из этого правила есть исключения, и они возникают, когда клиент желает сохранить контроль над структурой расположения ресурсов, которые он развертывает. Это редко и, вероятно, означает, что что-то не так.

На этом этапе некоторые люди будут утверждать, что если используются RESTful-URL, клиент знает URL-адрес ресурса, и поэтому PUT является приемлемым. В конце концов, именно поэтому канонические, нормализованные, Ruby on Rails, URL-адреса Django важны, посмотрите на Twitter API… бла-бла-бла. Эти люди должны понимать, что не существует такой вещи, как Restful-URL, и что сам Рой Филдинг заявляет:

REST API не должен определять фиксированные имена ресурсов или иерархии (очевидная связь клиента и сервера). Серверы должны иметь возможность управлять своим собственным пространством имен. Вместо этого разрешите серверам инструктировать клиентов о том, как создавать соответствующие URI, например, как это делается в формах HTML и шаблонах URI, путем определения этих инструкций в типах мультимедиа и отношениях ссылок. [Отказ здесь означает, что клиенты предполагают структуру ресурсов из-за внеполосной информации, такой как стандарт для домена, который является ориентированным на данные эквивалентом функционального связывания RPC].

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Идея RESTful-URL на самом деле является нарушением REST, поскольку сервер отвечает за структуру URL-адреса и должен иметь право решать, как его использовать, чтобы избежать связывания. Если это смущает, вы читаете о значении самопознания для разработки API.

Использование POST для создания ресурсов требует особого внимания при разработке, поскольку POST не является идемпотентным. Это означает, что повторение POST несколько раз не гарантирует каждый раз одно и то же поведение. Это пугает людей, заставляя их использовать PUT для создания ресурсов, хотя им этого не следует. Они знают, что это неправильно (POST для CREATE), но они все равно это делают, потому что не знают, как решить эту проблему. Это беспокойство проявляется в следующей ситуации:

1. Клиент POST новый ресурс на сервер.
2. Сервер обрабатывает запрос и отправляет ответ.
3. Клиент никогда не получает ответа.
4. Сервер не знает, что клиент не получил ответ.
5. У клиента нет URL-адреса для ресурса (поэтому PUT не вариант) и повторяет POST.
6. POST не идемпотентен, и сервер…

На шаге 6 люди обычно не понимают, что им делать. Однако нет причин создавать кладж для решения этой проблемы. Вместо этого можно использовать HTTP, как указано в RFC 2616, и сервер отвечает:

10.4.10 409 Конфликт

Запрос не может быть выполнен из-за конфликта с текущим состоянием ресурса. Этот код разрешен только в ситуациях, когда ожидается, что пользователь сможет разрешить конфликт и повторно отправить запрос. Тело ответа ДОЛЖНО включать достаточно

информация, позволяющая пользователю распознать источник конфликта. В идеале объект ответа должен включать достаточно информации для пользователя или пользовательского агента, чтобы исправить проблему; однако это может быть невозможно и не требуется.

Конфликты наиболее вероятны в ответ на запрос PUT. Например, если использовалось управление версиями и объект PUT включал изменения ресурса, которые конфликтуют с изменениями, сделанными более ранним (сторонним) запросом, сервер может использовать ответ 409, чтобы указать, что он не может выполнить запрос. . В этом случае объект ответа, вероятно, будет содержать список различий между двумя версиями в формате, определенном Content-Type ответа.

Ответ с кодом состояния 409 Conflict является правильным средством защиты, потому что:

• Выполнение POST данных с идентификатором, который соответствует ресурсу, уже находящемуся в системе, является «конфликтом с текущим состоянием ресурса».
• Поскольку важная часть для клиента состоит в том, чтобы понять, что у сервера есть ресурс, и предпринять соответствующие действия. Это «ситуации, когда ожидается, что пользователь сможет разрешить конфликт и повторно отправить запрос».
• Ответ, содержащий URL-адрес ресурса с конфликтующим идентификатором и соответствующие предварительные условия для ресурса, предоставит «достаточно информации для пользователя или пользовательского агента, чтобы решить проблему», что является идеальным случаем для RFC 2616.

Обновление основано на выпуске RFC 7231 на замену 2616

RFC 7231 разработан для замены 2616 и в Раздел 4.3.3 описывает следующий возможный ответ на POST.

Если результат обработки POST будет эквивалентен представлению существующего ресурса, исходный сервер МОЖЕТ перенаправить пользовательский агент на этот ресурс, отправив ответ 303 (см. Другое) с идентификатором существующего ресурса в поле Location. Это дает преимущества предоставления пользовательскому агенту идентификатора ресурса и передачи представления с помощью метода, более подходящего для совместного кэширования, хотя и за счет дополнительного запроса, если пользовательский агент еще не кэшировал представление.

Теперь может возникнуть соблазн просто вернуть 303 в случае повторения POST. Однако верно обратное. Возврат 303 имеет смысл только в том случае, если несколько запросов на создание (создание разных ресурсов) возвращают один и тот же контент. Примером может служить «спасибо за отправку сообщения с запросом», которое клиенту не нужно повторно загружать каждый раз. RFC 7231 по-прежнему утверждает в разделе 4.2.2, что POST не должен быть идемпотентным, и продолжает утверждать, что POST должен использоваться для создания.

Для получения дополнительной информации об этом прочтите этот статья.

Мне нравится этот совет из определения PUT в RFC 2616:

Принципиальное различие между запросами POST и PUT отражается в различном значении Request-URI. URI в запросе POST идентифицирует ресурс, который будет обрабатывать вложенный объект. Этот ресурс может быть процессом приема данных, шлюзом к другому протоколу или отдельным объектом, принимающим аннотации. Напротив, URI в запросе PUT идентифицирует объект, заключенный с запросом - пользовательский агент знает, какой URI предназначен, и сервер НЕ ДОЛЖЕН пытаться применить запрос к какому-либо другому ресурсу.

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

Я интерпретирую это и требования идемпотентности к PUT так:

• POST хорош для создания новых объектов в коллекции (и create не обязательно должно быть идемпотентным)
• PUT хорош для обновления существующих объектов (и обновление должно быть идемпотентным)
• POST также может использоваться для неидемпотентных обновлений существующих объектов (особенно для изменения части объекта без указания всего объекта целиком - если подумать, создание нового члена коллекции на самом деле является частным случаем такого рода обновление, с точки зрения коллекции)
• PUT также можно использовать для создания, если и только если вы разрешаете клиенту называть ресурс. Но поскольку клиенты REST не должны делать предположений о структуре URL-адресов, это не соответствует предполагаемому духу вещей.

Суммируя:

PUT является идемпотентным, при этом состояние ресурса будет одинаковым, если одна и та же операция выполняется один или несколько раз.

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

Аналогия с запросом к базе данных

PUT Вы можете думать о том, что похоже на ОБНОВЛЕНИЕ СТУДЕНЧЕСКОГО НАБОРА address = abc, где id = 123;

POST Вы можете придумать что-то вроде INSERT INTO STUDENT (имя, адрес) VALUES (abc, xyzzz);

Идентификатор студента создается автоматически.

При использовании PUT, если один и тот же запрос выполняется несколько раз или один раз, состояние таблицы STUDENT остается неизменным.

В случае POST, если один и тот же запрос выполняется несколько раз, в базе данных создается несколько записей Student, и состояние базы данных изменяется при каждом выполнении запроса INSERT.

ПРИМЕЧАНИЕ. PUT требует местоположения ресурса (уже ресурса), в котором должно произойти обновление, тогда как POST этого не требует. Поэтому интуитивно POST предназначен для создания нового ресурса, тогда как PUT необходим для обновления уже существующего ресурса.

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

POST похож на отправку письма в почтовый ящик или отправку электронного письма в очередь электронной почты. PUT - это то же самое, что когда вы кладете объект в нишу или место на полке (у него известный адрес).

С помощью POST вы отправляете сообщение на адрес QUEUE или COLLECTION. С помощью PUT вы вводите адрес ITEM.

PUT идемпотентен. Вы можете отправить запрос 100 раз, и это не имеет значения. POST не идемпотентен. Если вы отправите запрос 100 раз, вы получите 100 писем или 100 писем в свой почтовый ящик.

Общее правило: если вы знаете идентификатор или имя элемента, используйте PUT. Если вы хотите, чтобы идентификатор или имя элемента были присвоены принимающей стороной, используйте POST.

Новый ответ (теперь, когда я лучше понимаю REST):

PUT - это просто заявление о том, какой контент с этого момента служба должна использовать для визуализации представлений ресурса, идентифицированного клиентом; POST - это заявление о том, какой контент отныне должен содержать сервис (возможно, дублированный), но как идентифицировать этот контент, зависит от сервера.

PUT x (если x идентифицирует ресурс): " Заменить содержание ресурса, обозначенного x, моим содержанием ".

PUT x (если x не идентифицирует ресурс): «Создать новый ресурс, содержащий мой контент, и использовать x для его идентификации».

POST x: «Сохраните мой контент и дайте мне идентификатор, который я могу использовать для идентификации ресурса (старого или нового), содержащего указанный контент (возможно, смешанный с другим контентом). Указанный ресурс должен быть идентичен или подчинен тому, который идентифицирует x». «Ресурс y подчиняется ресурсу x» обычно, но не обязательно, реализуется путем превращения y в подпуть x (например, x = /foo и y = /foo/bar) и изменение представления (-ий) ресурса x, чтобы отразить наличие нового ресурса, например с гиперссылкой на ресурс y и некоторыми метаданными. Только последнее действительно важно для хорошего дизайна, поскольку URL-адреса в REST непрозрачны - вместо этого вы должны использовать гипермедиа. создания URL на стороне клиента для обхода службы в любом случае.

В REST нет такого понятия, как ресурс, содержащий «контент». Я называю "содержанием" данные, которые служба использует для последовательной визуализации представлений. Обычно он состоит из некоторых связанных строк в базе данных или файле (например, файле изображения). Служба должна преобразовать контент пользователя во что-то, что служба может использовать, например преобразование полезной нагрузки JSON в операторы SQL.

Исходный ответ (возможно, будет удобнее читать):

PUT /something (если /something уже существует): «Возьмите все, что у вас есть в /something, и замените это тем, что я вам даю».

PUT /something (если /something еще не существует): "Возьми то, что я даю тебе, и поставь на /something."

POST /something: "Возьмите то, что я вам даю, и поместите его где угодно под /something, пока вы дадите мне его URL, когда закончите."

Краткий ответ:

Простое практическое правило: используйте POST для создания, используйте PUT для обновления.

Длинный ответ:

ПОЧТА:

• POST используется для отправки данных на сервер.
• Полезно, когда URL ресурса неизвестен

ПОЛОЖИЛ:

• PUT используется для передачи состояния на сервер
• Полезно, когда известен URL-адрес ресурса

Более длинный ответ:

Чтобы понять это, нам нужно спросить, зачем нужен PUT, какие проблемы PUT пытался решить, а POST не мог.

С точки зрения архитектуры REST нет ничего важного. Мы могли бы жить и без PUT. Но с точки зрения разработчика-клиента это сделало его жизнь намного проще.

До PUT клиенты не могли напрямую знать URL-адрес, сгенерированный сервером, и все ли они были сгенерированы, а также данные, которые должны быть отправлены на сервер, уже обновлены или нет. PUT избавил разработчика от всех этих головных болей. PUT является идемпотентным, PUT обрабатывает условия гонки, а PUT позволяет клиенту выбирать URL-адрес.

Ruby on Rails 4.0 будет использовать метод PATCH вместо PUT для частичного обновления.

RFC 5789 говорит о PATCH (с 1995 года):

Необходим новый метод для улучшения взаимодействия и предотвращения ошибок. Метод PUT уже определен для перезаписи ресурса полностью новым телом и не может быть повторно использован для частичных изменений. В противном случае прокси и кеши, и даже клиенты и серверы могут запутаться в результате операции. POST уже используется, но без широкой совместимости (например, нет стандартного способа обнаружить поддержку формата исправлений). PATCH упоминался в более ранних спецификациях HTTP, но не полностью определен.

"Edge Rails: PATCH - это новый основной метод HTTP для обновлений ", - объясняет это.

Рискуя повторить то, что уже было сказано, важно помнить, что PUT подразумевает, что клиент контролирует то, чем в конечном итоге будет URL, при создании ресурс. Таким образом, часть выбора между PUT и POST будет заключаться в том, насколько вы можете доверять клиенту в предоставлении правильного, нормализованного URL, который согласуется с любой вашей схемой URL-адресов.

Если вы не можете полностью доверять тому, что клиент поступает правильно, было бы более целесообразно использовать POST для создания нового элемента, а затем отправить URL-адрес обратно клиенту в ответе.

Очень просто я возьму пример временной шкалы Facebook.

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

Случай 2: Если ваш друг прокомментирует ваше сообщение в первый раз, это также создаст новую запись в базе данных, чтобы использовать метод POST.

Случай 3: Если ваш друг редактирует свой комментарий, в этом случае у него был идентификатор комментария, поэтому он обновит существующий комментарий вместо создания новой записи в базе данных. Поэтому для этого типа операции используйте метод PUT, потому что он идемпотентен. *

В одной строке используйте POST, чтобы добавить новую запись в базу данных, и PUT, чтобы обновить что-либо в база данных.

Наиболее важным фактором является надежность. Если сообщение POST потеряно, состояние системы не определено. Автоматическое восстановление невозможно. Для сообщений PUT состояние не определено только до первой успешной попытки.

Например, создание транзакций по кредитным картам с помощью POST может быть не очень хорошей идеей.

Если у вас есть автоматически сгенерированные URI на вашем ресурсе, вы все равно можете использовать PUT, передав сгенерированный URI (указывающий на пустой ресурс) клиенту.

Некоторые другие соображения:

• POST делает недействительными кэшированные копии всего содержащего ресурса (лучшая согласованность)
• Ответы PUT не кэшируются, в то время как ответы POST (требуется Content-Location и срок действия)
• PUT менее поддерживается, например, Java ME, старые браузеры, брандмауэры

Помимо различий, предложенных другими, я хочу добавить еще одно.

В методе POST вы можете отправлять параметры тела в form-data

В методе PUT вы должны отправить параметры тела в x-www-form-urlencoded

Заголовок Content-Type:application/x-www-form-urlencoded

В соответствии с этим вы не можете отправлять файлы или составные данные в методе PUT.

ИЗМЕНИТЬ

Тип содержимого «application / x-www-form-urlencoded» неэффективен для отправки больших объемов двоичных данных или текста, содержащих символы, отличные от ASCII. Тип содержимого «multipart / form-data» следует использовать для отправки форм, содержащих файлы, данные, отличные от ASCII, и двоичные данные.

Это означает, что если вам нужно отправить

файлы, данные не в формате ASCII и двоичные данные

вам следует использовать метод POST

Читателей, плохо знакомых с этой темой, поразят бесконечные дискуссии о том, что вы должны делать, и относительное отсутствие уроков из опыта. Тот факт, что REST «предпочтительнее» SOAP, - это, я полагаю, высокий уровень обучения на собственном опыте, но, черт возьми, мы, должно быть, продвинулись дальше? Это 2016 год. Диссертация Роя была в 2000 году. Что мы разработали? Это было весело? Было ли легко интегрироваться с? Поддерживать? Сможет ли он справиться с ростом количества смартфонов и нестабильной мобильной связи?

По мнению ME, реальные сети ненадежны. Таймаут запросов. Подключения сброшены. Сети выходят из строя на часы или дни. Поезда идут в туннели с мобильными пользователями на борту. Для любого заданного запроса (что иногда признается во всех этих обсуждениях) запрос может упасть в воду на своем пути, или ответ может упасть в воду на обратном пути. В этих условиях отправка запросов PUT, POST и DELETE непосредственно против основных ресурсов всегда казалась мне немного грубой и наивной.

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

Или вы можете сделать это: рассматривайте свои небезопасные запросы как эфемерные однопользовательские ресурсы (назовем их действиями). Клиенты запрашивают новое «действие» над основным ресурсом с пустым POST для ресурса. POST будет использоваться только для этого. Получив безопасный доступ к URI только что созданного действия, клиент отправляет небезопасный запрос на URI действия, не на целевой ресурс. Разрешение действия и обновление «реального» ресурса - это должная работа вашего API, и здесь она отделена от ненадежной сети.

Сервер выполняет свою работу, возвращает ответ и сохраняет его в соответствии с согласованным URI действия. Если что-то пойдет не так, клиент повторяет запрос (естественное поведение!), А если сервер уже видел его, он повторяет сохраненный ответ и больше ничего не делает.

Вы быстро заметите сходство с обещаниями: мы создаем и возвращаем заполнитель для результата, прежде чем что-либо делать. Также как и обещание, действие может быть успешным или неудачным один раз, но его результат может быть получен повторно.

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

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

Последовательные запросы на удаление могут видеть и обрабатывать исходное подтверждение, не вызывая ошибки 404. Если что-то займет больше времени, чем ожидалось, мы можем дать предварительный ответ, и у нас есть место, где клиент может проверить окончательный результат. Самая приятная часть этого узора - его свойство Кунг-Фу (Панда). Мы берем слабость, склонность клиентов повторять запрос каждый раз, когда они не понимают ответа, и превращаем его в сильную сторону :-)

Прежде чем сказать мне, что это не RESTful, пожалуйста, рассмотрите многочисленные способы соблюдения принципов REST. Клиенты не создают URL-адреса. API остается доступным для обнаружения, хотя и с небольшим изменением семантики. Глаголы HTTP используются правильно. Если вы думаете, что это огромное изменение, которое нужно реализовать, я могу сказать вам по опыту, что это не так.

Если вы думаете, что вам нужно хранить огромные объемы данных, давайте поговорим об объемах: типичное подтверждение обновления составляет доли килобайта. HTTP в настоящее время дает вам минуту или две для окончательного ответа. Даже если вы храните действия только в течение недели, у клиентов есть много шансов наверстать упущенное. Если у вас очень большие объемы, вам может потребоваться специальное хранилище значений ключей, совместимое с кислотами, или решение в памяти.

Кажется, всегда существует некоторая путаница относительно того, когда использовать HTTP POST по сравнению с методом HTTP PUT для служб REST. Большинство разработчиков попытаются связать операции CRUD напрямую с методами HTTP. Я буду утверждать, что это неверно, и нельзя просто связать концепции CRUD с методами HTTP. То есть:

Create => HTTP PUT
Retrieve => HTTP GET
Update => HTTP POST
Delete => HTTP DELETE

Верно, что R (etrieve) и D (elete) операций CRUD могут быть сопоставлены непосредственно с HTTP-методами GET и DELETE соответственно. Однако путаница заключается в операциях C (reate) и U (update). В некоторых случаях можно использовать PUT для создания, а в других случаях потребуется POST. Неоднозначность заключается в определении метода HTTP PUT по сравнению с методом HTTP POST.

Согласно спецификациям HTTP 1.1, методы GET, HEAD, DELETE и PUT должны быть идемпотентными, а метод POST не идемпотентным. То есть операция является идемпотентной, если она может выполняться с ресурсом один или несколько раз и всегда возвращать одно и то же состояние этого ресурса. В то время как неидемпотентная операция может возвращать измененное состояние ресурса от одного запроса к другому. Следовательно, в неидемпотентной операции нет гарантии, что будет получено такое же состояние ресурса.

Основываясь на приведенном выше определении идемпотента, я предлагаю использовать метод HTTP PUT по сравнению с использованием метода HTTP POST для служб REST: Используйте метод HTTP PUT, когда:

The client includes all aspect of the resource including the unique identifier to uniquely identify the resource. Example: creating a new employee.
The client provides all the information for a resource to be able to modify that resource.This implies that the server side does not update any aspect of the resource (such as an update date).

В обоих случаях эти операции могут выполняться несколько раз с одинаковыми результатами. То есть ресурс не будет изменен запросом операции более одного раза. Следовательно, настоящая идемпотентная операция. Используйте метод HTTP POST, когда:

The server will provide some information concerning the newly created resource. For example, take a logging system. A new entry in the log will most likely have a numbering scheme which is determined on the server side. Upon creating a new log entry, the new sequence number will be determined by the server and not by the client.
On a modification of a resource, the server will provide such information as a resource state or an update date. Again in this case not all information was provided by the client and the resource will be changing from one modification request to the next. Hence a non idempotent operation.

Заключение

Не коррелируйте напрямую и не сопоставляйте операции CRUD с методами HTTP для служб REST. Использование метода HTTP PUT по сравнению с методом HTTP POST должно основываться на идемпотентном аспекте этой операции. То есть, если операция идемпотентная, используйте метод HTTP PUT. Если операция неидемпотентная, используйте метод HTTP POST.

исходный сервер может создать ресурс с этим URI

Таким образом, вы используете POST и, возможно, но не обязательно PUT для создания ресурса. Необязательно поддерживать обоих. Для меня POST вполне достаточно. Так что это дизайнерское решение.

Как уже упоминалось в вашей цитате, вы используете PUT для создания ресурса, назначенного IRI, и вы все равно хотите создать ресурс. Например, PUT /users/123/password обычно заменяет старый пароль новым, но вы можете использовать его для создания пароля, если он еще не существует (например, для недавно зарегистрированных пользователей или для восстановления заблокированных пользователей).

Я собираюсь приземлиться со следующим:

PUT относится к ресурсу, идентифицированному URI. В этом случае вы обновляете его. Это часть трех глаголов, относящихся к ресурсам - удалить и получить, являясь двумя другими.

POST - это, по сути, сообщение в свободной форме, значение которого определяется как «внеполосное». Если сообщение можно интерпретировать как добавление ресурса в каталог, это будет нормально, но в основном вам нужно понимать сообщение, которое вы отправляете (публикуете), чтобы знать, что произойдет с ресурсом.

Поскольку PUT, GET и DELETE относятся к ресурсу, они также по определению идемпотентны.

POST может выполнять остальные три функции, но тогда семантика запроса будет потеряна посредниками, такими как кеши и прокси. Это также относится к обеспечению безопасности ресурса, поскольку URI сообщения не обязательно указывает на ресурс, к которому он применяется (хотя может).

PUT не обязательно должен быть созданием; служба может выдать ошибку, если ресурс еще не создан, но в противном случае обновите его. Или наоборот - он может создать ресурс, но не разрешить обновления. Единственное, что требуется от PUT, - это то, что он указывает на конкретный ресурс, а его полезная нагрузка - это представление этого ресурса. Успешный PUT означает (запрет на вмешательство), что GET получит тот же ресурс.

Изменить: еще одна вещь - PUT может создавать, но если это так, идентификатор должен быть естественным идентификатором - он же адрес электронной почты. Таким образом, когда вы дважды помещаете PUT, вторая операция PUT является обновлением первой. Это делает его идемпотентным.

Если сгенерирован идентификатор (например, новый идентификатор сотрудника), то второй оператор PUT с тем же URL-адресом создаст новую запись, что нарушает идемпотентное правило. В этом случае глагол будет POST, а сообщение (не ресурс) будет создавать ресурс с использованием значений, определенных в этом сообщении.

Предполагается, что семантика будет разной: «PUT», как «GET», должен быть идемпотентным - это означает, что вы можете один и тот же точный запрос PUT несколько раз, и результат будет таким, как если бы вы выполнили его только один раз.

Я опишу соглашения, которые, на мой взгляд, наиболее широко используются и наиболее полезны:

Когда вы помещаете ресурс по определенному URL-адресу, происходит то, что он должен быть сохранен по этому URL-адресу или чему-то в этом роде.

Когда вы отправляете POST на ресурс по определенному URL-адресу, вы часто публикуете связанную информацию по этому URL-адресу. Это означает, что ресурс по URL-адресу уже существует.

Например, если вы хотите создать новый поток, вы можете ПОСТАВИТЬ его на какой-нибудь URL. Но если вы хотите отправить сообщение в существующий поток, вы отправляете сообщение на его URL-адрес.

Что касается изменения свойств потока, вы можете сделать это с помощью PUT или POST. В принципе, используйте "PUT" только тогда, когда операция идемпотентна - в противном случае используйте POST.

Однако обратите внимание, что не все современные браузеры поддерживают команды HTTP, кроме GET или POST.

В большинстве случаев вы будете использовать их так:

• POST ресурса в коллекцию
• PUT ресурс, идентифицированный коллекцией /: id

Например:

• POST / шт.
• PUT / items / 1234

В обоих случаях тело запроса содержит данные для ресурса, который будет создан или обновлен. Из имен маршрутов должно быть очевидно, что POST не является идемпотентным (если вы вызовете его 3 раза, он создаст 3 объекта), но PUT является идемпотентным (если вы вызовете его 3 раза, результат будет таким же). PUT часто используется для операции «upsert» (создание или обновление), но вы всегда можете вернуть ошибку 404, если хотите использовать ее только для изменения.

Обратите внимание, что POST «создает» новый элемент в коллекции, а PUT «заменяет» элемент по заданному URL-адресу, но это очень распространенная практика - использовать PUT для частичных изменений, то есть использовать его только для обновления существующих ресурсов и изменять только включенные поля в теле (игнорируя другие поля). Это технически неверно, если вы хотите быть сторонником REST, PUT должен заменить весь ресурс, и вы должны использовать PATCH для частичного обновления. Мне лично все равно, насколько четкое и последовательное поведение для всех ваших конечных точек API.

Помните, что REST - это набор соглашений и рекомендаций, призванных упростить ваш API. Если вы столкнетесь со сложным обходным путем, просто чтобы поставить отметку в поле «RESTfull», значит, вы теряете цель;)

Вот простое правило:

PUT в URL-адрес следует использовать для обновления или создания ресурса, который может быть расположен по этому URL-адресу.

POST к URL-адресу следует использовать для обновления или создания ресурса, который расположен по другому («подчиненному») URL-адресу или не может быть обнаружен через HTTP.

Если вы знакомы с операциями с базами данных, есть

1. Выбирать
2. Вставлять
3. Обновлять
4. Удалить
5. Объединить (обновить, если уже существует, иначе вставить)

Я использую PUT для операций слияния и обновления, а также POST для вставок.

Хотя, вероятно, существует агностический способ описания этого, он, похоже, противоречит различным утверждениям из ответов на веб-сайтах.

Давайте будем очень ясными и прямыми. Если вы разработчик .NET, работающий с веб-API, факты (из документации Microsoft API) следующие: http://www.asp.net/web-api/overview/creating-web-apis/create-a-web-api-that-supports-crud-operations:

1. PUT = UPDATE (/api/products/id)
2. MCSD Exams 2014 -  UPDATE = PUT, there are **NO** multiple answers for that question period.

Конечно, вы «можете» использовать «POST» для обновления, но просто следуйте соглашениям, изложенным для вас с вашей данной структурой. В моем случае это .NET / Web API, поэтому PUT для UPDATE не вызывает споров.

Я надеюсь, что это поможет любым разработчикам Microsoft, которые читают все комментарии со ссылками на веб-сайты Amazon и Sun / Java.

На практике POST хорошо работает для создания ресурсов. URL-адрес вновь созданного ресурса должен быть возвращен в заголовке ответа Location. PUT следует использовать для полного обновления ресурса. Пожалуйста, поймите, что это лучшие практики при разработке RESTful API. Спецификация HTTP как таковая не ограничивает использование PUT / POST с некоторыми ограничениями для создания / обновления ресурсов. Взгляните на http://techoctave.com/c7/posts/71-twitter-rest-api-dissected, в котором обобщены лучшие практики.

POST: используйте его для создания новых ресурсов. Это похоже на INSERT (оператор SQL) с автоматически увеличивающимся идентификатором. В ответной части он содержит новый сгенерированный идентификатор.

POST также используется для обновления записи.

PUT: используйте его для создания нового ресурса, но здесь я знаю идентификационный ключ. Это похоже на INSERT (оператор SQL), где я заранее знаю идентификационный ключ. В ответной части он ничего не отправляет.

PUT также используется для обновления ресурса

Методы запроса GET, PUT и DELETE являются операциями управления данными низкого уровня (см. RFC 7231, § 4.3.1, § 4.3.4 и § 4.3.5 ), т.е. операции CRUD (создание, чтение, обновление и удаление), на состояние ресурса target (идентифицируемого URI запроса):

• GET должен читать представление о состоянии целевого ресурса;
• PUT должен создать или обновить состояние целевого ресурса с помощью представления запроса;
• DELETE должен удалить состояние целевого ресурса.

Напротив, метод запроса POST - это операция обработки высокого уровня (см. RFC 7231, § 4.3.3), то есть не-CRUD операция. POST должен обрабатывать представление запроса. Обработка может создать состояние ресурса, но для ресурса, отличного от целевого ресурса. Он не должен создавать или обновлять состояние целевого ресурса с помощью представления запроса, потому что для этого сделана более конкретная операция CRUD PUT, как объяснил Рой Филдинг в своей статье блога Можно использовать POST:

POST становится проблемой только тогда, когда он используется в ситуации, для которой идеально подходит какой-либо другой метод: например, поиск информации, которая должна быть представлением некоторого ресурса (GET), полная замена представления (PUT) или любой из другие стандартизированные методы, которые сообщают посредникам нечто более ценное, чем «это может что-то изменить». Другие методы более ценны для посредников, потому что они говорят о том, как можно автоматически обрабатывать сбои и как можно оптимизировать промежуточные кеши. их поведение. POST не обладает этими характеристиками, но это не значит, что мы можем жить без него. POST служит многим полезным целям в HTTP, включая общую цель: «это действие не стоит стандартизировать».

Таким образом, фундаментальное различие между операциями CRUD (GET, PUT и DELETE в HTTP) и операциями без CRUD (POST в HTTP) заключается в уровне абстракции. Алан Кей говорил об этой разнице в контексте объектно-ориентированного программирования в большинстве своих выступлений и в своей статье по ACM Ранняя история Smalltalk (выделено мной):

Что я получил от Simula, так это то, что теперь вы можете заменить привязки и назначения целями. Последнее, что вы хотели бы от любого программиста, - это возиться с внутренним состоянием, даже если оно представлено образно. Вместо этого объекты должны быть представлены как сайты более высокого уровня поведения, более подходящие для использования в качестве динамических компонентов.

[…] К сожалению, большая часть того, что сегодня называют объектно-ориентированным программированием, представляет собой простое программирование в старом стиле с более причудливыми конструкциями. Многие программы загружены операциями в стиле присваивания, которые теперь выполняются более дорогими присоединенными процедурами.

[…] Заявления о назначении - даже абстрактные - выражают очень низкоуровневые цели, и для выполнения чего-либо потребуется их больше. […] Еще один способ подумать обо всем этом: хотя позднее связывание автоматического выделения памяти не делает ничего такого, что не может сделать программист, его присутствие приводит как к более простому, так и к более мощному коду. ООП - это стратегия позднего связывания для многих вещей, и все они вместе сдерживают хрупкость и рост размеров намного дольше, чем старые методологии.

Итак, какой из них следует использовать для создания ресурса? Или нужно поддерживать и то, и другое?

Вы должны использовать PATCH. Вы ПАТЧИВАЕТЕ список вопросов вроде

PATCH /questions HTTP/1.1

со списком, содержащим ваш объект, который будет создан, например

[
    {
        "title": "I said semantics!",
        "content": "Is this serious?",
        "answer": "Not really"
    }
]

Это запрос PATCH как

• вы изменяете существующий список ресурсов , не предоставляя полностью новый контент
• вы меняете состояние своего нового вопроса с несуществующего на существующий без предоставления всех данных (сервер, скорее всего, добавит id).

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

Это то, чего PUT явно не может. Вы можете использовать POST для создания нескольких объектов, поскольку это кухонная раковина HTTP и может делать практически все.

Недостатком является то, что, вероятно, никто не использует PATCH таким образом. Боюсь, это я только что придумал, но надеюсь, что дал хорошую аргументацию.

Вместо этого вы можете использовать CREATE, поскольку пользовательские HTTP-команды разрешены, просто они могут не работать с некоторыми инструментами.

Что касается семантики, CREATE - ИМХО единственный правильный выбор, все остальное - квадратный колышек в круглое отверстие. К сожалению, все, что у нас есть, - это круглые дырочки.

Я думаю, что есть также интересный момент, о котором не говорили в этом вопросе PUT vs POST:

Если вы хотите иметь веб-приложение, которое работает без JavaScript (например, если кто-то использует браузер командной строки, такой как Lynx, или надстройку браузера, например NoScript или uMatrix), вам придется использовать POST для отправки данных, поскольку формы HTML поддерживают только HTTP-запросы GET и POST.

Обычно, если вы хотите использовать прогрессивное улучшение (https://en.wikipedia.org/wiki/Progressive_enhancement), чтобы ваше веб-приложение работало везде, с JavaScript и без него, вы не можете использовать другие HTTP-методы, такие как PUT или DELETE, которые были добавлены только в HTTP версии 1.1.

Дополнение ко всем ответам выше:

Чаще всего используется в профессиональной практике,

• мы используем PUT вместо POST в операции CREATE. Почему? потому что многие здесь также сказали, что ответы не кэшируются, в то время как ответы POST (Требовать Content-Location и срок действия).
• Мы используем POST поверх PUT в операции UPDATE. Почему? потому что он делает недействительными кэшированные копии всего содержащего ресурса. что полезно при обновлении ресурсов.