я ответил ранее, но этот ответ противоречит моему старому ответу и следует совсем другой стратегии решения проблемы. Это показывает, как HTTP-запрос построен из концепций, определяющих REST и HTTP. Он также использует PATCH вместо POST или PUT.

Он проходит через ограничения REST, затем компоненты HTTP, а затем - возможное решение.

REST

REST - это набор ограничений, предназначенных для применения к распределенной системе гипермедиа, чтобы сделать его масштабируемым. Даже чтобы понять это в контексте дистанционного управления действием, вам нужно подумать о дистанционном контроле действия как части распределенной системы гипермедиа - части системы для обнаружения, просмотра и изменения взаимосвязанной информации. Если это больше проблем, чем стоит, то, вероятно, не стоит пытаться сделать это RESTful. Если вам просто нужен GUI типа "панель управления" на клиенте, который может инициировать действия на сервере через порт 80, то вам, вероятно, нужен простой интерфейс RPC, такой как JSON-RPC через HTTP-запросы/ответы или WebSocket.

Но REST - это увлекательный образ мышления, и пример в этом вопросе легко моделируется с помощью интерфейса RESTful, поэтому давайте возьмем вызов для удовольствия и образования.

REST определяется четырьмя ограничениями интерфейса:

идентификация ресурсов; манипулирование ресурсами через представления; самоописательные сообщения; и гипермедиа как двигатель состояния приложения.

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

Начнем с первого ограничения: идентификация ресурса.

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

Итак, собака - это ресурс. Он должен быть идентифицирован.

Точнее, ресурс R представляет собой временно изменяющуюся функцию принадлежности M _R (t), которая для времени t отображает на набор сущностей или значений, которые эквивалентны. Значениями в наборе могут быть представления ресурсов и/или идентификаторы ресурсов.

Вы моделируете собаку, беря набор идентификаторов и представлений и заявляя, что все они связаны друг с другом в данный момент времени. В настоящее время позвольте использовать идентификатор "dog # 1". Это приводит нас ко второму и третьему ограничениям: представление ресурсов и самоописание.

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

Ниже приведена последовательность байтов, фиксирующая предполагаемое состояние собаки, то есть представление, которое мы хотим связать с идентификатором "собака № 1" (обратите внимание, что он представляет только часть состояния, так как он не считает собаку имя, здоровье или даже прошлые лаки):

Он лает каждые 10 минут с момента его изменения и будет продолжаться бесконечно.

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

Это английское утверждение. Он описывает часть предполагаемого состояния. Если он принят несколько раз, разрешите только первый эффект.

Наконец, посмотрим на четвертое ограничение: HATEOAS.

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

В интерфейсе RESTful клиент получает представление ресурса, чтобы выяснить, как он должен получать или отправлять представление. Должно быть какое-то представление в приложении, из которого клиент может выяснить, как получать или отправлять все представления, которые он должен получать или отправлять, даже если он следует цепочке представлений, чтобы получить эту информацию. Это кажется достаточно простым:

Клиент запрашивает представление ресурса, идентифицированного как домашняя страница; в ответ он получает представление, которое содержит идентификатор каждой собаки, которую может пожелать клиент. Клиент извлекает из него идентификатор и спрашивает службу, как он может взаимодействовать с идентифицированной собакой, и служба говорит, что клиент может отправить английское выражение, описывающее часть предполагаемого состояния собаки. Затем клиент отправляет такой оператор и получает сообщение об успешном завершении или сообщение об ошибке.

HTTP

HTTP реализует ограничения REST следующим образом:

идентификация ресурса: URI

представление ресурса: entity-body

самоописание: код метода или состояния, заголовки и, возможно, части тела сущности (например, URI схемы XML)

HATEOAS: гиперссылки

Вы выбрали http://api.animals.com/v1/dogs/1 как URI. Предположим, что клиент получил это с некоторой страницы на сайте.

Позвольте использовать этот объект-тело (значение next является меткой времени, значение 0 означает "когда этот запрос получен" ):

{"barks": {"next": 0, "frequency": 10}}

Теперь нам нужен метод. PATCH соответствует описанию "части предполагаемого состояния", мы решили:

Метод PATCH запрашивает, чтобы набор изменений, описанных в объекте запроса, был применен к ресурсу, идентифицированному Request-URI.

И некоторые заголовки:

Чтобы указать язык тела объекта: Content-Type: application/json

Чтобы убедиться, что это происходит только один раз: If-Unmodified-Since: <date/time this was first sent>

И у нас есть запрос:

PATCH /v1/dogs/1/ HTTP/1.1
Host: api.animals.com
Content-Type: application/json
If-Unmodified-Since: <date/time this was first sent>
[other headers]

{"barks": {"next": 0, "frequency": 10}}

В случае успеха клиент должен получить 204 код статуса в ответ или 205, если представление /v1/dogs/1/ изменилось, чтобы отразить новый график лай.

При сбое он должен получить 403 и полезное сообщение.

Не обязательно REST для службы отражать расписание коры в представлении в ответ на GET /v1/dogs/1/, но это было бы наиболее разумно, если бы представление JSON включало это:

"barks": {
    "previous": [x_1, x_2, ..., x_n],
    "next": x_n,
    "frequency": 10
}

Рассматривайте задание cron как деталь реализации, которую сервер скрывает от интерфейса. Это красота универсального интерфейса. Клиент не должен знать, что делает сервер за кулисами; все, о чем он заботится, заключается в том, что служба понимает и отвечает запрошенным изменениям состояния.

Большинство людей используют POST для этой цели. Он подходит для выполнения "любой небезопасной или неидентичной операции, когда никакой другой метод HTTP не подходит".

API, такие как XMLRPC, используют POST для запуска действий, которые могут запускать произвольный код. "Действие" включено в данные POST:

POST /RPC2 HTTP/1.0
User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181

<?xml version="1.0"?>
<methodCall>
   <methodName>examples.getStateName</methodName>
   <params>
      <param>
         <value><i4>41</i4></value>
         </param>
      </params>
   </methodCall>

Приводится пример RPC, показывающий, что POST является обычным выбором HTTP-глаголов для серверных методов. Здесь мысли Роя Филдинга о POST - он в значительной степени говорит, что RESTful использует HTTP-методы, как указано.

Обратите внимание, что сам RPC не очень RESTful, потому что он не ориентирован на ресурсы. Но если вам нужна безгражданность, кеширование или расслоение, нетрудно сделать соответствующие преобразования. См. http://blog.perfectapi.com/2012/opinionated-rpc-apis-vs-restful-apis/ для примера.

POST - метод HTTP, разработанный для

Предоставление блока данных... процессу обработки данных

Серверные методы обработки не-CRUD-отображаемых действий - это Рой Филдинг, предназначенный с REST, так что вы там хороши, и почему POST было сделано неидемпотентным. POST будет обрабатывать большинство сообщений на серверных методах обработки информации.

Тем не менее, в сценарии вашей собачьей лайки, если вы хотите, чтобы кору серверной стороны выполняли каждые 10 минут, но по какой-то причине требуется запуск триггера от клиента, PUT будет служить цели лучше, из-за его идемпотентности. Ну, строго по этому сценарию нет явного риска множественных запросов POST, заставляющих вашу собаку мяукать, но в любом случае цель этих двух подобных методов. Мой ответ на аналогичный вопрос SO может быть вам полезен.

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

POST http://api.animals.com/v1/dogs/1/bark

собака номер 1 лает

GET http://api.animals.com/v1/dogs/1/bark

возвращает последнюю метку времени коры

DELETE http://api.animals.com/v1/dogs/1/bark

не применяется! поэтому игнорируйте его.

В предыдущих версиях некоторых ответов вы предлагали использовать RPC. Вам не нужно искать RPC, так как вы можете делать то, что хотите, придерживаясь ограничений REST.

Во-первых, не указывайте параметры действия в URL. URL-адрес определяет, к чему вы применяете действие, и параметры запроса являются частью URL-адреса. Его следует рассматривать исключительно как существительное . http://api.animals.com/v1/dogs/1/?action=bark - это другой ресурс - другое существительное - http://api.animals.com/v1/dogs/1/. [Нотабене Asker удалил URI ?action=bark из вопроса.] Например, сравните http://api.animals.com/v1/dogs/?id=1 с http://api.animals.com/v1/dogs/?id=2. Различные ресурсы, выделенные только строкой запроса. Таким образом, действие вашего запроса, если оно не соответствует непосредственно существующему типу метода bodyless (TRACE, OPTIONS, HEAD, GET, DELETE и т.д.), Должно быть определено в теле запроса.

Затем определите, является ли действие " idempotent", что означает, что его можно повторить без неблагоприятного эффекта (см. следующий абзац для более подробного объяснения), Например, установка значения true может быть повторена, если клиент не уверен в том, что желаемый эффект произошел. Они снова отправляют запрос, и значение остается верным. Добавление 1 к числу не является идемпотентным. Если клиент отправляет команду Add1, не уверен, что он сработал, и отправляет его еще раз, добавил ли сервер один или два? После того, как вы определили, что у вас есть лучшее место для выбора между PUT и POST для вашего метода.

Idempotent означает, что запрос может быть повторен без изменения результата. Эти эффекты не включают регистрацию и другие действия администратора сервера. Используя первый и второй примеры, отправка двух электронных писем одному человеку приводит к другому состоянию, чем отправка одного электронного письма (у получателя есть два в своем почтовом ящике, который они могут считать спамом), поэтому я бы определенно использовал POST для этого, Если barkCount в примере 2 предназначен для просмотра пользователем вашего API или затрагивает то, что видимо для клиента, то это также то, что сделало бы запрос неидемпотентным. Если он должен быть просмотрен только вами, он учитывается как ведение журнала сервера и должен быть проигнорирован при определении idempotentcy.

Наконец, определите, можно ли ожидать, что действие, которое вы хотите выполнить, преуспеть немедленно или нет. BarkDog - это быстро завершающее действие. RunMarathon - нет. Если ваше действие происходит медленно, подумайте о возврате 202 Accepted с URL-адресом в теле ответа для опроса пользователя, чтобы узнать, завершено ли действие. Кроме того, у пользователей POST есть URL-адрес списка, например /marathons-in-progress/, а затем, когда действие будет выполнено, перенаправляйте их с URL-адреса прогресса в URL-адрес /marathons-complete/.
Для конкретных случаев № 1 и № 2 у меня будет очередь хоста сервера, и клиент отправляет партии адресов к нему. Действие не будет SendEmails, но что-то вроде AddToDispatchQueue. Затем сервер может опросить очередь, чтобы узнать, есть ли какие-либо адреса электронной почты, и отправить электронные письма, если они найдут. Затем он обновляет очередь, чтобы указать, что ожидающее действие теперь выполнено. У вас будет другой URI, показывающий клиенту текущее состояние очереди. Чтобы избежать двойной отправки сообщений электронной почты, сервер также мог сохранить журнал того, кому он отправил это письмо, и проверить каждый адрес на это, чтобы гарантировать, что он никогда не отправит два на тот же адрес, даже если вы дважды отправляете один и тот же список очередь.

При выборе URI для чего-либо, попробуйте думать об этом как результат, а не о действии. Например, google.com/search?q=dogs показывает результаты поиска слова "собаки". Это не обязательно выполняет поиск.

Случаи №3 и №4 из вашего списка также не являются идемпотентными действиями. Вы предполагаете, что различные предлагаемые эффекты могут повлиять на дизайн API. Во всех четырех случаях я бы использовал один и тот же API, поскольку все четыре меняют "мировое состояние".

См. мой новый ответ. Это противоречит этому и объясняет REST и HTTP более четко и точно.

Здесь рекомендация, которая оказалась RESTful, но, конечно, не единственная опция. Чтобы начать лаять, когда услуга получает запрос:

POST /v1/dogs/1/bark-schedule HTTP/1.1
...
{"token": 12345, "next": 0, "frequency": 10}

token - произвольное число, которое предотвращает избыточные лаки, независимо от того, сколько раз этот запрос отправляется.

next указывает время следующей коры; значение 0 означает "ASAP".

Всякий раз, когда вы GET /v1/dogs/1/bark-schedule, вы должны получить что-то вроде этого, где t - время последней коры, и u равно t + 10 минут:

{"last": t, "next": u}

Я настоятельно рекомендую вам использовать тот же URL-адрес, чтобы запросить кору, которую вы используете, чтобы узнать о текущем состоянии лай собаки. Это не важно для REST, но в нем подчеркивается акт изменения расписания.

Соответствующий код состояния, вероятно, 205. Я представляю клиента, который смотрит текущее расписание, POST на тот же URL-адрес, чтобы изменить его, и ему поручается служба, чтобы дать графику второй взгляд, чтобы доказать, что он был изменен.

Объяснение

REST

Забудьте об HTTP на мгновение. Необходимо понимать, что ресурс - это функция, которая требует времени для ввода и возвращает набор, содержащий идентификаторы и представления. Пусть это упростит: ресурс представляет собой набор R идентификаторов и представлений; R может меняться - члены могут быть добавлены, удалены или изменены. (Хотя это плохой, нестойкий дизайн для удаления или изменения идентификаторов.) Мы говорим, что идентификатор, являющийся элементом R, идентифицирует R, и что представление, являющееся элементом R, представляет R.

Скажем, что R - собака. Вы обнаруживаете R как /v1/dogs/1. (Значение /v1/dogs/1 является членом R.) Это всего лишь один из многих способов идентифицировать R. Вы также можете идентифицировать R как /v1/dogs/1/x-rays и как /v1/rufus.

Как вы представляете R? Может быть, с фотографией. Может быть, с набором рентгеновских лучей. Или, может быть, с указанием даты и времени, когда R последний лаял. Но помните, что это все представления одного и того же ресурса. /v1/dogs/1/x-rays является идентификатором того же ресурса, который представлен ответом на вопрос "когда была R последняя кора?"

HTTP

Несколько представлений ресурса не очень полезны, если вы не можете ссылаться на тот, который вам нужен. Вот почему HTTP полезен: он позволяет связывать идентификаторы с представлениями. То есть, это способ для службы получить URL-адрес и решить, какое представление будет обслуживать клиент.

По крайней мере, то, что делает GET. PUT в основном является обратным к GET: you PUT представление r в URL-адресе, если вы хотите, чтобы будущие запросы GET к этому URL-адресу возвратили r, с некоторыми возможными переводами, такими как JSON в HTML.

POST является более свободным способом изменения представления. Подумайте, есть ли логика отображения и логика модификации, которые являются аналогами друг друга - оба соответствуют одному и тому же URL. Запрос POST - это запрос логики модификации для обработки информации и изменения любых представлений (а не только представления, расположенного по тому же URL-адресу), что и служба. Обратите внимание на третий абзац после 9.6 PUT: вы не заменяете вещь на URL с новым контентом; вы запрашиваете у объекта URL-адрес для обработки некоторой информации и интеллектуального ответа в форме информационных представлений.

В нашем случае мы запрашиваем логику модификации в /v1/dogs/1/bark-schedule (которая является аналогом логики отображения, которая сообщает нам, когда она в последний раз лает и когда она будет следующей корой) обрабатывать нашу информацию и соответственно модифицировать некоторые представления. В ответ на будущие GET s логика отображения, соответствующая тому же URL-адресу, сообщит нам, что собака теперь лает по своему желанию.

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

REST - это ориентированный на ресурсы стандарт, это не действие, управляемое как RPC.

Если вы хотите, чтобы ваш сервер лаял, вы должны изучить различные идеи, такие как JSON-RPC, или в обмен сообщениями в сети.

Каждая попытка сохранить RESTful на мой взгляд: вы можете выдать POST с параметром action, вы не создаете никаких новых ресурсов, но поскольку у вас могут быть побочные эффекты, вы более безопасны.