разработка действий в REST API - когда RESTful слишком RESTful?
Я занимаюсь разработкой REST API для проекта, над которым мы работаем. То есть я пишу спецификации, которые будут реализованы позже.
У меня проблемы с размышлением о существительных / ресурсах вместо действий / глаголов . Не вдаваясь в подробности проекта, мы пишем API для SVN. Например, выполните действие, которое фиксирует изменения на сервере SVN. В нашем проекте у нас есть несколько определений / версий действия фиксации:
- просто зафиксировать все измененные файлы
- зафиксировать список измененных файлов (подмножество, а не весь набор измененных файлов)
- .. .
(1) Как бы вы разработали URL-адрес? Первый вопрос: как описать действие фиксации как существительное / ресурс вместо глагола ?
Кто-то скажет:
POST/PUT http://server.com/api/revision/commit
Это должно быть POST или PUT? На самом деле я не создаю ресурс фиксации , поэтому это не POST. Однако на самом деле я не меняю ресурс фиксации , поэтому это не PUT. На самом деле это не ресурс , это действие . Как только действие выполнено, оно исчезает, нет ресурсов, которые нужно создать, изменить или сохранить для дальнейшего использования.
Тем не менее, это должен быть ресурс, поэтому URL-адрес, вероятно, должен быть таким.
POST http://server.com/api/revision/commitment
Это также POST, поскольку мы создаем обязательство. Мы ничего не меняем, поэтому PUT нет. Также обратите внимание, что я изменил фиксацию на обязательство , чтобы отразить тот факт, что мы имеем дело с ресурсами.
Имеет ли это смысл? Для меня это не так, это сводит меня с ума. Я хочу выполнить действие, а не создать ресурс, похожий на действие. Но в любом случае.
Тем не менее, идя дальше, я просто создал ресурс для обязательств. По логике вещей, я смогу получить его позже:
GET http://server.com/api/revision/commitment/:id
Но нет ресурса для обязательств! Я был вынужден сделать это, чтобы оставаться в состоянии ОТДЫХА. head explodes
Итак, как на самом деле указать действия с ресурсами в REST API? Я не говорю о типах действий, которые создают ресурс (создать пользователя, ...), а о видах действий, которые манипулируют ресурсом или воздействуют на ресурс (фиксация ревизии, ...).
( 2) Затем, во-вторых, в случае второго определения (см. Выше), как нам указать подмножество измененных файлов? Через параметры или в какую-то структуру (например, массив JSON) в ТЕЛЕ? Какой из них предпочтительнее? Есть ли какие-то общие правила?
Всем спасибо!