Использует ли глагол в URL-адресе принципиально несовместимый с REST?

Итак, скажем, у нас есть что-то, что кажется не лучшим в качестве ресурса (статус процесса, который мы хотим приостановить, расчет без учета состояния, который мы хотим выполнить на сервере, и т.д.).

Если в дизайне API мы используем либо process/123/pause, либо calculations/fibonacci - это принципиально несовместимо с REST? До сих пор я не читал это, пока эти URL-адреса не могут быть обнаружены с использованием HATEOAS и стандартизированы типы носителей.

Или я должен предпочесть включить действие в сообщение в ответ на здесь?

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

Примечание 2:
Ответ "REST не имеет каких-либо ограничений для этого" будет правильным ответом (что будет означать, что этот подход RESTful). Ответы "это зависит от того, кого вы спрашиваете" или "это лучшая практика", на самом деле не отвечают на вопрос. Вопрос предполагает, что концепция REST существует как четко определенный общий термин, который два человека могут использовать для обозначения одного и того же набора ограничений. Если само предположение неверно и формальное обсуждение REST не имеет смысла, скажите об этом.

Ответ 1

Это не строго о существительных против глаголов; это о том, являетесь ли вы:

идентификация ресурсов
управление ресурсами через представления

Какой ресурс? Филдинг определяет это следующим образом:

Ключевая абстракция информации в REST - это ресурс. Любая информация, которая может быть названа, может быть ресурсом: документ или изображение, временная служба (например, "сегодня погода в Лос-Анджелесе" ), коллекция других ресурсов, не виртуальный объект (например, человек) и т.д., Другими словами, любое понятие, которое может быть объектом гипертекстовой ссылки автора, должно соответствовать определению ресурса. Ресурс представляет собой концептуальное сопоставление с набором объектов, а не с сущностью, которая соответствует отображению в любой конкретный момент времени.

Теперь, на ваш вопрос. Вы не можете просто взглянуть на URL-адрес и сказать: "Является ли такой-то URL-адрес принципиально несовместимым с REST?" потому что URL-адреса в системе REST на самом деле не являются важным битом. Более важно, чтобы URL-адреса process/123/pause и calculations/fibonacci идентифицировали ресурсы по вышеуказанному определению. Если это так, нарушение ограничений REST отсутствует. Если это не так, вы нарушаете унифицированное ограничение интерфейса REST. Ваш пример заставляет меня думать, что он не соответствует определению ресурса и, следовательно, нарушит это ограничение.

Чтобы проиллюстрировать, какой ресурс может быть в этой системе, вы можете изменить статус процесса, отправив его в коллекцию ресурсов paused-processes. Хотя это, пожалуй, необычный способ работы с процессами, он принципиально несовместим с стилем архитектуры REST.

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

Request:
GET /calculations/5

Response:
{
  fibonacci: 5,
  prime-number: true,
  square-root: 2.23607
}

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

Request:
GET /stored-calculations/12381728 (note that URL is a random identifier)

Response:
{
  number: 5,
  fibonacci: 5,
  prime-number: true,
  square-root: 2.23607
}

хотя предположительно вы хотите сохранить дополнительную информацию об этом ресурсе, кроме простого расчета, который любой может сделать с калькулятором...

Response:
{
  number: 5,
  fibonacci: 5,
  prime-number: true,
  square-root: 2.23607,
  last-accessed-date: 2013-10-28T00:00:00Z,
  number-of-retrievals-of-this-resource: 183
}

Ответ 2

В этой статье есть несколько полезных советов: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Цитата из статьи:

Как насчет действий, которые не вписываются в мир операций CRUD?

Здесь вещи могут стать нечеткими. Существует несколько подходов:

Перестройте действие, чтобы оно выглядело как поле ресурса. Это работает, если действие не принимает параметры. Например, действие активации может быть отображено в логическое активированное поле и обновлено через PATCH для ресурса.

Рассматривайте его как под-ресурс с принципами RESTful. Например, API-интерфейс GitHub позволяет отображать gist с помощью PUT/gists/: id/star и notar с помощью DELETE/gists/: id/star.

Иногда у вас действительно нет способа сопоставить действие с разумной структурой RESTful. Например, поиск по нескольким ресурсам на самом деле целесообразно применять к определенной конечной точке ресурса. В этом case/search будет иметь наибольший смысл, даже если он не является существительным. Это нормально - просто сделайте, что с точки зрения API и убедитесь, что он четко документирован, чтобы избежать путаницы.

Мне лично нравится предложение №2. Если вам нужно что-то приостановить, что вы делаете паузой? Если это процесс с именем, попробуйте это:

/process/{processName}/pause

Ответ 3

Он считал, что неправильная практика использования глаголов в вашем REST API.

Там есть материал на fooobar.com/questions/25864/... и в других местах, почему и как избежать использования глаголов. При этом существует множество API-интерфейсов REST, которые используют глаголы.

Для вашего API process я бы сделал ресурс Process иметь поле state, которое можно изменить с помощью PUT.

Предположим, что GET /process/$id возвращает:

{
   state: "PAUSED"
}

Затем вы PUT на /process/$id:

{
   state: "RUNNING"
}

что делает состояние изменения процесса.

В случае с Фибоначчи просто укажите ресурс с именем fibonacci и используйте POST с параметрами (например, n для первых n чисел фибоначчи) в теле или, возможно, даже GET с запросом в URL.

Ответ 4

Метод HTTP - это глагол: GET, PUT, POST и т.д., в то время как URL-адрес должен всегда ссылаться на существительное (получатель действия). Подумайте об этом так: будут ли два глагола в предложении иметь смысл? "GET calculate" - это вздор, где "состояние GET" является хорошим и "процесс GET" лучше ( "состояние" является метаданных для процесса).