REST API с несколькими командами на ресурс

Question

У меня есть вопрос относительно дизайна REST API.Вот простой (возможно, слишком простой) API:

GET /ecommerce/order/123

POST /ecommerce/order (create a new order)

PUT /ecommerce/order/123 (update an existing order)

DELETE /ecommerce/order/123 (cancel order)

Но что, если я бы хотел, чтобы клиент указал причину отмены заказа?Мне нужно будет отправить данные поста в API, но это не будет работать с DELETE.Чтобы удовлетворить это, я должен был бы изменить УДАЛЕНИЕ на PUT.Затем я бы опубликовал два разных ресурса для обновления и отмены.

Другое решение было бы изменить API:

GET /ecommerce/order/123

POST /ecommerce/order/create (create a new order)

PUT /ecommerce/order/update/123 (update an existing order)

DELETE /ecommerce/order/cancel/123 (cancel order)

Я не уверен, какой вариант лучше.

Существует более общий вопрос о том, как REST API обрабатывает несколько команд для одного ресурса.

Любой ввод будет оценен по достоинству!Я собираюсь читать REST на практике очень скоро, но этот вопрос утомляет меня.

Answer 1

Одним из вариантов может быть создание нового ресурса. CancelledOrder, возможно.

Тогда вы можете POST новый CancelledOrder:

POST /ecommerce/cancelledOrder
Entity:
    order: /ecommerce/order/123
    reason: "Problem with order"

Вы также можете / вместо PUT a CancelledOrder:

PUT /ecommerce/cancelledOrder/123
Entity:
    reason "Problem with order"

Приложение может затем удалить заказ 123 или изменить его статус на «Отменено», или выполнить все, что требуется в соответствии с вашими бизнес-правилами. В довершение всего, вы можете не поддерживать метод DELETE напрямую для /ecommerce/order/N, возвращая 405 Method Not Allowed.

Решение PUT может использовать идемпотентность в своих интересах; * * * * * * * * * * * * * * * * * * * * * * * * * * PUT * * * * * * Несколько раз CancelledOrder всегда будут приводить к отмене заказа.

Следует отметить, что ваши предложения по изменению API (например, /ecommerce/order/create), скорее всего, не будут RESTful, поскольку вы определяете методы в идентификаторах ресурсов.

Answer 2

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

POST / ecommerce / order / 123 / cancel

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

Answer 3

(Вопрос довольно старый, но я просто подумал, что смогу его улучшить, поскольку мне не нравятся какие-либо решения.)

Решение простое.Укажите причину в теле запроса.

DELETE /ecommerce/order/123
Content-Type: text/plain
Content-Length: 48

Order was cancelled due to a customer's request.

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

По моему мнению, это намного лучше, чем Javaesque RPC-подобный OrderCancellator.execute(order) (потому что POST - это имя HTTP для "execute"").

Помните, что хотя spec ничего не говорит об этом, некоторые серверы могут отбросить тело запроса DELETE .Черновик по семантике сообщений HTTP / 1.1 уточняет:

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

Другой вариант - выдать заголовок:

DELETE /ecommerce/order/123
X-Reason: Cancelled due to an UFO invasion.

Всякий раз, когда выбираются заголовки илиТело сущности зависит от размера и формата данных.Некоторые данные хорошо вписываются в заголовки HTTP, некоторые нет.Конечно, можно передать числовой идентификатор билета, он не уверен в строках (например, в Юникоде) и уверен, что никто в своем здравом уме не хочет передавать туда Base64 JPEG.