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

Question

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

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

Какие-либо предложения?

Answer 1

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

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: Использование указывает, что запрос не может быть выполнен из-за конфликта с текущим состоянием целевого ресурса.

Answer 2

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

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

Следовательно, идиоматически представление, которое вы отправляете на сервер REST, является представлением сообщения TODO, и вы отправляете его либо на (a) ресурс, который представляет "входящие", то есть конкретную коллекцию сообщений TODO, или (b) ресурс, который представляет сам документ TODO.

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

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

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

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

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

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

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

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

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

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