Глагол REST для изменения состояния - можем ли мы договориться о POST?

Вы можете отправить запрос частичного обновления с HTTP PATCH, который содержит только новое состояние.

PATCH /coffeemachines/{id}
{
    status: "active"
}

Согласно Википедии :

Метод PATCH - это метод запроса, поддерживаемый протоколом HTTP для внесения частичных изменений в существующий ресурс. Метод PATCH предоставляет объект, содержащий список изменений, которые должны быть применены к ресурсу, запрошенному с использованием HTTP URI. Список изменений представлен в форме документа PATCH.

Также удобнее разделять слова в пути с помощью дефисов. Например:

PATCH /coffee-machines/{id}
{
    status: "active"
}

Глагол REST для изменения состояния - можем ли мы договориться о POST?

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

Использование POST для небезопасных операций прекрасно .

Хотя start выглядит как глагол (нарушающий REST-практики)

Нет - REST не заботится о написании URI. В этом и заключается суть: сервер может в любой момент изменить URI в ссылках, так как клиенты просто переходят по ссылкам.

Тем не менее, есть проблема с предложенными вами идентификаторами, которую вы можете рассмотреть

/coffeemachines/{id}
/coffeemachines/{id}/start

Что касается REST, то это различных ресурсов. Это означает, что ваша локально кэшированная копия /coffeemachines/{id} не является недействительной , когда вы POST запросите к /coffeemachines/{id}/start.

Если вы хотите воспользоваться преимуществами поддержки кэширования, которая уже встроена в независимые от домена компоненты, то вы хотите, чтобы цель POST соответствовала цели GET: /coffeemachines/{id} [ 1135]

/coffeemachines/{id}/start, в этом дизайне, не является целью POST, но вместо этого является идентификатором ресурса формы, который отправляет стартовые сообщения в /coffeemachines/{id}. Аналогично, /coffeemachines/{id}/stop идентифицирует ресурс формы, который отправляет сообщения остановки.

Представление кофемашины будет включать ссылки на эти формы, когда переходы разрешены; например, когда кофемашина выключена, то представление кофемашины, возвращенное GET, будет включать ссылку на стартовую форму, но не ссылку на форму остановки.

/coffeemachines/{id}/start и /coffeemachines/{id}/stop отличаются от ресурсов /coffeemachines/{id} и поэтому могут иметь свои собственные политики кэширования.

Конечно, не требуется , чтобы формы были отдельными ресурсами - механизм также работал бы, если бы формы были частью представления самого ресурса /coffeemachines/{id}.

Могу ли я попросить вас рассказать о POST против PATCH

Я обнаружил, что это наблюдение Роя Филдинга мне помогло:

[ 1142] HTTP не пытается требовать, чтобы результаты GET были безопасными. Для этого требуется, чтобы семантика операции была безопасной, и, следовательно, это ошибка реализации, а не интерфейса или пользователя этого интерфейса, если в результате произойдет что-либо, что приведет к потере свойства

PATCH имеет более строгую семантику, чем POST ; это означает, что клиенты (и общие компоненты) могут сделать более сильными предположения о том, что происходит.

Так в следующих примерах:

PATCH /foo HTTP/1.1
Content-Type: application/json-patch+json

POST /foo HTTP/1.1
Content-Type: application/json-patch+json

Сервер может обрабатывать эти сообщения точно таким же образом. Клиенты, которые распознают метод PATCH, распознают, что небезопасные изменения на сервере должны быть «все или ничего» («Сервер ДОЛЖЕН применять весь набор изменений атомарно ...») и могут использовать это по своему усмотрению, но с POST это дополнительное ограничение отсутствует и не может быть принято.

Спецификация PATCH отмечает:

Сравнение с POST еще сложнее, потому что POST используется в самых разных ситуациях и может охватывать операции PUT и PATCH, если сервер выбирает. Если операция не изменяет ресурс, идентифицируемый Request-URI предсказуемым образом, следует рассмотреть POST вместо PATCH или PUT.