Какой HTTP-запрос RESTful для выполнения действий на сервере?

У меня есть API-интерфейс RESTFul, который я создал. Некоторые его части не контролируют ресурсы, и мне не удается сопоставить соответствующий URL + HTTP-метод с действиями, которые выполняются на сервере.

например. Я могу сделать резервную копию каждого ресурса на сервере с помощью POST /backup, но я не уверен, что это наиболее подходящее сопоставление. Как насчет единого ресурса? Должен ли я указывать его с помощью: POST /backup/id или объявлением id как переменной, которую я отправляю: POST /backup <id>

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

Ответ 1

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

POST /backups используется для создания нового объекта и, следовательно, правильный ответ, если вы всегда создаете новую резервную копию.

PUT /backups/id, если вы обновляете данные резервного копирования в одном и том же объекте.

Ответ 2

Я верю, что POST /backup (для резервного копирования всех ресурсов) и POST /backup <id> (для резервного копирования одного ресурса) вам подойдет.

CRUD MAPPING: Как сказал Рэй, резервная копия не отображает на CRUD; вам нужен ресурс действий на сервере для выполнения функции. Марк Массе написал книгу O'Reilly по дизайну API REST и его рекомендация - использовать ресурс действия на сервере в этом случае (см. слайд 20 в архетипе действия).

НАЗНАЧЕНИЕ URI: Ресурсы действий должны быть последним сегментом URI без каких-либо дочерних ресурсов. Это будет иметь смысл, когда вы увидите причину ниже, для которой метод HTTP лучше всего подходит здесь.

МЕТОД HTTP: Резервное копирование не должно быть idempotent, поэтому вы хотите, чтобы HTTP-метод не идемпотент, Это POST. Идет не только ИДЕМПТЕНТ, но и указанный вами URI - это место, где вы отправляете ресурс, который вы отправляете. Вы не хотите этого делать, если хотите успокоиться. Часть цели POST и ее не-idempotence указано как

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

что вы хотите здесь.

REST Чтобы быть многоуровневой системой, сервер (посредством своего ресурса действия (метод резервного копирования)) должен указать, куда должен идти его выход; клиент не должен вмещать эту логику.

Итак, сделав это так, ваш ресурс действия резервного копирования может определить, где вы хотите поместить резервные копии (который может быть ресурсом магазина (/backups), см. слайд 19) и хотите ли вы перезаписать предыдущие резервные копии или хотите ли вы реализовать определенную форму управления версиями (что не учитывает дизайн REST). Так что в основном вы были на правильном пути!

Ответ 3

В то время как RESTafarians (REST purists) скажут, что единственными действиями в REST API должны быть основные операции CRUD, которые отображают HTTP-глаголы - GET, PUT, POST и DELETE - это иногда это не практично и затрудняет работу, чем это должно быть. Если вы хотите иметь другие действия, такие как "Резервное копирование", тогда вам может потребоваться реализация REST в стиле RPC, которая использует как HTTP-глагол, так и имя действия, встроенное в URL-адрес запроса, для определения выполняемого действия.

GET    /resource/select
GET    /resource/select?id={id}
PUT    /resource/update?id={id}
POST   /resource/insert
DELETE /resource/delete?id={id}
PUT*   /resource/backup?id={id}
GET    /resource/backup?id={id}

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

Ответ 4

Вы можете использовать POST /backups?resource=car&id=123 для резервного копирования автомобиля с id = 123 (конечно, вы можете передать объект JSON вместо параметров в URL, если хотите). Обратите внимание также на множественное число в резервных копиях, это деталь, но она лучше сообщает о том, что в этом URI можно найти одну или несколько резервных копий.

Если вы хотите заменить ранее созданную резервную копию, то, как упоминалось выше, вы можете использовать PUT, может быть, как этот PUT /backups/456?resource=car&id=123, который говорит: "Замените резервную копию id = 456 той, которую вы создадите из резервной копии автомобиль с id = 123".

Наконец, если вы хотите сделать резервную копию всех своих ресурсов за один шаг, у вас может быть соответствующий параметр, например POST /backups?all=true или аналогичный. И если вы хотите, чтобы эти резервные копии заменили предыдущие, перед запуском этого использования вы можете использовать DELETE /backups.