ПОСТАВИТЬ, ПОСТАТЬ или ПАТЧАТЬ?

Замена состояния ресурса

REST не зависит от протокола и ориентирован на ресурсы. архитектура. Например, при реализации приложений REST по протоколу HTTP ресурс идентифицируется по URI, а операция над ресурсом выражается в разделе метод HTTP.

PUT — это метод HTTP, используемый для замены состояния ресурса и новое состояние ресурса будет выражено в полезной нагрузке запроса с использованием, например, JSON и/или XML.

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

PUT /databases/:id/status HTTP/1.1
Content-Type: application/json

{
    "value": "started"
}

PUT /databases/:id/status HTTP/1.1
Content-Type: application/json

{
    "value": "stopped"
}

Чтобы получить состояние ресурса, используйте GET:

GET /databases/:id/status HTTP/1.1

Коды состояния ответа

Вам обязательно нужно будет сообщить клиенту о результате операции. Для этого используйте коды состояния ответов HTTP.

Несколько статусов, которые могут быть полезны:

• 200: используйте этот статус, чтобы указать, что запрос выполнен успешно.
• 202: используйте этот код состояния, чтобы указать, что запрос принят для обработки. , но обработка не завершена.
• 204: используйте этот код состояния, чтобы указать, что сервер успешно выполнил запрос. и что нет дополнительного содержимого для отправки в теле полезной нагрузки ответа.
• 409: указывает, что запрос не может быть выполнен из-за конфликт с текущим состоянием целевого ресурса.

Джим Уэббер объясняет, что HTTP — это прикладной протокол для передачи документов. Переходы состояния в вашем приложении — это побочный эффект, вызванный передачей документа.

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

Таким образом, идиоматически представление, которое вы отправляете на сервер REST, представляет собой сообщение TODO, и вы отправляете его либо (а) ресурсу, который представляет папку «Входящие», т. е. определенному набору сообщений TODO, либо ( б) ресурс, представляющий сам документ TODO.

У меня есть служба REST, которую можно использовать для управления базами данных, я хочу разрешить вызовы для остановки и запуска баз данных, но мне интересно, какой метод будет правильным?

Вызывая операцию Stop или Start, я изменяю состояние ресурса, поэтому PUT кажется правильным, но PATCH лучше или даже POST?

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

DELETE также не подходит — удаление аналогично уничтожению сообщения TODO в папке «Входящие».

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

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

Если вы доставляете представление одного сообщения ресурсу, который представляет только это сообщение (т. е. вы создаете ресурс сообщения), то PUT предпочтительнее POST. Ключевая идея здесь заключается в том, что PUT обещает, что любые побочные эффекты на сервере являются идемпотентными — побочный эффект успешной доставки N › 0 копий сообщения эквивалентен побочному эффекту доставки ровно 1 копии. . Использование PUT в качестве глагола разделяет это обещание не только с клиентом и сервером, но и со всеми промежуточными соединителями на этом пути.

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

(Пример: подумайте о сообщении формы в браузере. Ресурс на сервере знает, что запрос может быть обработан идемпотентно. Вы можете документировать в самом html, что нажатие кнопки более одного раза безопасно, но у вас нет никаких способ сообщить браузеру об этом, чтобы браузер выдал пользователю сообщение о том, что повторная отправка POST может быть небезопасной, вы уверены, что да/нет?)

Таким образом, вы хотите, чтобы ваш выбор HTTP-методов согласовывался с унифицированным интерфейсом, чтобы клиент, сервер и все компоненты, работающие с сообщениями, имели общее понимание того, что происходит. на.