Разработка действий в REST API - когда RESTful тоже RESTful?

Я занимаюсь разработкой REST API для проекта, над которым мы работаем. То есть, я пишу спецификации, которые будут реализованы позже.

У меня возникают проблемы, чтобы думать о существительных/ресурсах вместо действий/глаголов. Не вдаваясь в слишком много особенностей проекта, мы пишем API вокруг SVN. Например, выполните действие, которое совершает изменения на сервере SVN. В нашем проекте мы имеем несколько определений/версий действия фиксации:

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

(1) Как бы вы создали URL-адрес? Первый вопрос: как описать действие commit как существительное/ресурс вместо глагола?

Кто-то сказал бы:

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

Но ресурсов для обязательств нет! Я был вынужден сделать один, чтобы быть RESTful. голова взрывается

Итак, как вы действительно указываете действия по ресурсам в REST API? Я не говорю о типах действий, которые создают ресурс (создайте пользователя,...), но о типах действий, которые манипулируют ресурсом или действуют на ресурсе (фиксировать ревизию,...).

(2) Затем, во-вторых, в случае второго определения (см. выше), как мы определяем подмножество измененных файлов? Через параметры или в некоторой структуре (например, массив JSON) в BODY? Какой из них предпочтительнее? Существуют ли общие правила?

Спасибо всем!

Ответ 1

Иногда проще создавать резервные копии в дизайне URL, чем идти вперед. Мне кажется, что то, что вы называете "обязательством", на самом деле является самой ревизией. svn commit в основном означает, "пожалуйста, примите эти отличия от моей выбранной в настоящее время ревизии как новую (дочернюю) ревизию". Поэтому вам необходимо определить текущую выбранную ревизию (чтобы оставаться без гражданства), а затем добавить к ней значимым образом:

POST http://server.com/api/revisions/16/children/

То есть POST-объект, который инкапсулирует отличия от ревизии 16. Затем сервер может ответить 201 Created, плюс Location: /api/revisions/23/ (или /api/revisions/16/children/1, который перенаправляется на первый).

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

Ответ 2

Остановить мышление в действиях; D

Прежде всего, ваш SVN будет основан на файле и не основан на базе данных, что поможет в мышлении.

Если вы думаете об этом, у вас есть только 3 restfull (ну на самом деле, возможно, 4) операции в вашем репозитории: svn add + svn commit, чтобы поместить новый файл под управлением версией. Это переводит в PUT в папку, в которую вы хотите добавить и зафиксировать файл. svnroot:/project/folder на самом деле, так как "id" файла известен, вы действительно можете PUT непосредственно по URL-адресу файла: svnroot:/project/folder/file.c

Вы хотите зафиксировать изменение, которое переводится на POST на ресурсе (а не в папке, кроме фактического существующего файла в этой папке). POST svnroot:/project/folder/file.c

Если вы хотите удалить файл, то obvioulsy - это DELETE.

Если вы хотите узнать, какой номер версии для определенного файла использует STATUS.

Начните думать о том, что происходит на самом деле, а не о том, как вызываются глаголы (co, ci, add, update и т.д.), что происходит в том, что файлы "созданы" в репозитории, то есть PUT или изменены, то есть POST или удаленный/удаленный, то есть DELETE или запрашивается статус, который является STATUS.

Если вы извлекаете файл, это, очевидно, GET.

Итак, это выше - это действующий ресурс. Теперь вы можете придумать больше функций, указать размер файла и автора или последнего коммитера или сообщение фиксации! Теперь вам нужно работать с URL-адресами, для которых нет реального ресурса. Некоторые называют эти виртуальные ресурсы.

Просто добавьте "/authors" и т.д. в конец URL-адресов ресурсов и используйте POST, чтобы добавить автора и GET, чтобы прочитать авторов. (Материя вкуса, вы также могли бы использовать PUT, возможно, были бы более чистыми в соответствии с парадигмой REST)