• Вызов серверного метода на ресурс в спокойный путь

    Имейте в виду, у меня есть элементарное понимание отдыха. Допустим, у меня есть этот URL:

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

    И теперь, я хочу сделать сервер собака лает. Только сервер знает, как это делать. Допустим, я хочу запустить его на задание, что делает собака лает каждые 10 минут для остальной части вечности. Что значит что звонок похож? Я хочу сделать это:

    URL-адрес запроса:

    ACTION http://api.animals.com/v1/dogs/1/ 

    В тексте запроса:

    {"action":"bark"} 

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

    РЕДАКТИРОВАТЬ ДЛЯ РАЗЪЯСНЕНИЯ

    Более определенные разъяснения всего, что метод "кора" нет. Вот некоторые варианты, которые могут привести к В по-разному структурированных вызовов API:

    1. кора просто посылает по электронной почте к собаке.электронной почты и записей ничего.
    2. кора посылает по электронной почте к собаке.email и собаку шагом.по barkCount 1.
    3. коры создает новую "кора" записи с корой.записи отметок времени, когда кора произошло. Он также увеличивает собаку.по barkCount 1.
    4. кора выполняет команду системе, чтобы вытащить последнюю версию код собаку вниз с github. Затем он посылает текстовое сообщение на собаку.хозяин говорит им, что новый код собака находится в производстве.
  • Ответы

  • Зачем стремиться для спокойного дизайна?

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

    Простота обычный http (без мыла конверты и один-Ури перегружен POST услуг), что некоторые могут назвать "отсутствие возможностей", на самом деле его самая большая сила. С места в карьер, http просит Вас, чтобы иметь адресности и безгражданства: две основные конструктивные решения, которые держат на http масштабируемой до сегодняшнего мега-сайты (и мега-услуги).

    Но остальное не серебро bulltet: иногда в RPC-стиле (такие как мыло) может быть целесообразным, а иногда и другие потребности превалируют над достоинствами паутины. Это нормально. Что нам не нравится излишне сложности. Слишком часто программист или компания приносит в RPC-сервисов на работу, что старые http могла справиться просто отлично. Эффект является то, что http сводится к транспортный протокол за огромную полезную нагрузку XML, который объясняет, что "действительно" происходит (не Ури или http-метод дать подсказку об этом). В результате служба слишком сложна, невозможно отладить, и не будет работать, если ваши клиенты имеют точные настройки, как застройщик предполагал.

    Так же, как в Java/C# код может быть не объектно-ориентированный, просто через http не сделать дизайн спокойный. Может быть догнал в спешке , думая о своих услугах в плане действий и дистанционных методов , которые должны вызываться. Неудивительно, что это будет в конечном итоге в стиле RPC службы (или отдых-ЭКП-гибрид). Первый шаг, чтобы думать по-другому. Спокойный дизайн может быть достигнуто многими способами, один из способов (самый простой, можно сказать), чтобы думать о вашем заявлении в части средств, а не действия.

    Про первый дизайн

    Давайте взглянем предлагаемой конструкции:

    ACTION http://api.animals.com/v1/dogs/1/ 

    Во-первых, мы не должны рассмотреть вопрос о создании новой команды http (ACTION). Вообще говоря, это нежелательно по нескольким причинам:

    • (1) дано только обслуживание Ури, как будет "случайной" программист знать ACTION глагол существует?
    • (2) Если программист знает, что он существует, как он будет знать его семантику? Что это глагол означает?
    • (3) какие свойства (безопасность, idempotence) следует ожидать, что глагол иметь?
    • (4) Что делать, если программист имеет очень простой клиент, который только обрабатывает стандартных http-заголовков?
    • (5) ...

    Теперь давайте рассмотрим, используя POST (Мы обсудим ниже почему, просто поверьте мне на слово сейчас):

    POST /v1/dogs/1/ HTTP/1.1 Host: api.animals.com  {"action":"bark"} 

    Это может быть ок... но только если:

    • {"action":"bark"} документ; и
    • /v1/dogs/1/ был "процессор документов" (фабричный), Ури.

    Я не много знаю о вашей системе, но я бы уже ставить не только не соответствуют действительности:

    • {"action":"bark"} это не документ, это на самом деле - это метод, который вы пытаетесь ниндзя-скрытность в услужение; и
    • в /v1/dogs/1/ URI-это "собака" ресурс (вероятно, собака с id==1), а не процессор, документ.

    Итак, теперь мы знаем, что дизайн выше не столь спокойным, но что именно? Что в этом плохого? В принципе, это плохо, потому что это сложный Ури со сложными смыслами. Вы не можете сделать какой-либо вывод из него. Как программист знаю, собака есть bark действий, которые могут быть незаметно переплетаются с POST в нее?

    Проектирование API на Ваш вопрос требует

    Так что давайте ближе к делу уже и попробовать спроектировать те, лает спокойно, думая с точки зрения ресурсов. Позвольте мне процитировать веб-служб restful книги:

    А POST запрос-это попытка создать новый ресурс из существующего. Существующих ресурсов может быть родителем нового в данных-структура, смысл, путь корень дерева является родителем всех листовых узлов. Или существующий ресурс может быть особый "фабрики" ресурс, единственной целью которой является создание других ресурсов. Представительство отправляется вместе с POST запрос описывает начальное состояние нового ресурса. Как с говоря, POST запрос не должен включать в себя представление на всех.

    После приведенного выше описания, мы видим, что bark можно смоделировать как на ресурс из dogbark содержится в собаку, то есть кора "гавкнул" на собаку).

    Из этого рассуждения мы уже получили:

    • Метод POST
    • Ресурс /barks, ресурс-собаки: /v1/dogs/1/barks, представляющие собой bark "фабрики". Что URI является уникальным для каждой собаки (так как он находится под /v1/dogs/{id}).

    Теперь каждый случай свой список имеет определенное поведение.

    1. кора просто посылает по электронной почте к собаке.электронной почты и записей ничего.

    Во-первых, лает (отправка по электронной почте) синхронной или асинхронной задачи? Во-вторых bark запрос требует любой документ (письмо, может быть) или он пустой?

    1.1 кора посылает по электронной почте к собаке.email и записывает ничего (как синхронный задач)

    В этом случае проста. Вызов barks завод ресурс производит коры (также отправленные по электронной почте) сразу и ответ (если ОК или нет) дается сразу:

    POST /v1/dogs/1/barks HTTP/1.1 Host: api.animals.com Authorization: Basic mAUhhuE08u724bh249a2xaP=  (entity-body is empty - or, if you require a **document**, place it here)  200 OK 

    Как это записи (изменений) ничего, 200 OK достаточно. Это показывает, что все прошло как и ожидалось.

    1.2 кора посылает по электронной почте к собаке.email и записывает ничего (как асинхронной задачи)

    В этом случае, клиент должен иметь возможность отслеживать bark задач. В bark тогда задача должна быть ресурсом с собственной Ури.:

    POST /v1/dogs/1/barks HTTP/1.1 Host: api.animals.com Authorization: Basic mAUhhuE08u724bh249a2xaP=  (document body, if needed)  202 Accepted Location: http://api.animals.com/v1/dogs/1/bark/a65h44 

    Таким образом, каждый bark это прослеживается. После этого клиент может оформить GET к bark URI, чтобы знать его текущее состояние. Может быть, даже использовать DELETE отменить его.

    2. кора посылает по электронной почте к собаке.email и собаку шагом.по barkCount 1

    На этот раз может оказаться сложнее, если вы хотите, чтобы позволить клиенту знать dog ресурс меняется:

    POST /v1/dogs/1/barks HTTP/1.1 Host: api.animals.com Authorization: Basic mAUhhuE08u724bh249a2xaP=  (document body, if needed)  303 See Other Location: http://api.animals.com/v1/dogs/1 

    В этом случае location Заголовок намерением является, чтобы позволить клиенту знать, что он должен взглянуть на dog. Из протокол http RFC в о 303:

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

    Если задача асинхронного bark ресурс необходим только как 1.2 ситуации и 303 должны быть возвращены в GET .../bark/Y когда задача будет завершена.

    3. коры создает новую "кора" записи с корой.записи отметок времени, когда кора произошло. Он также увеличивает собаку.по barkCount 1.

    POST /v1/dogs/1/barks HTTP/1.1 Host: api.animals.com Authorization: Basic mAUhhuE08u724bh249a2xaP=  (document body, if needed)  201 Created Location: http://api.animals.com/v1/dogs/1/bark/a65h44 

    Здесь, в bark это создается благодаря запросу, поэтому статус 201 Created применяется.

    Если создание асинхронного 202 Accepted требуется (как в RFC по http говорит) вместо.

    Метка времени спас часть bark ресурсов и могут быть извлечены с GET к нему. Обновленный собака может быть "задокументированы" в том, что GET dogs/X/bark/Y также.

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

    Данная формулировка является сложным, но это в значительной степени простой асинхронной задачи:

    POST /v1/dogs/1/barks HTTP/1.1 Host: api.animals.com Authorization: Basic mAUhhuE08u724bh249a2xaP=  (document body, if needed)  202 Accepted Location: http://api.animals.com/v1/dogs/1/bark/a65h44 

    Тогда клиент будет выдавать GETs в /v1/dogs/1/bark/a65h44 чтобы узнать текущее состояние (если код был разобран, его е-мейл был отправлен к хозяину, и такие). Всякий раз, когда собака изменения, а 303 теперь применим.

    Заканчиваю

    Цитирую Рой Филдинг:

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

    В приведенных выше примерах, POST равномерно предназначены. Это сделает собака "bark". Что это не безопасный (что означает кора имеет влияния на ресурсы), ни идемпотентом (каждый запрос порождает новую bark), который соответствует POST глагол хорошо.

    Программист будет знать: POST в barks дает bark. Коды состояния ответ (также с лицом-телом и заголовки при необходимости) выполнить работу, объясняя, что изменилось и как клиент может и должно происходить.

    Примечание: основными источниками были: "restful веб-сервисы" книги, http в РФС и Рой Филдинг блоге.


    Обновление:

    На исходный вопрос задал про дизайн Ури, как:

    ACTION http://api.animals.com/v1/dogs/1/?action=bark 

    Ниже приводится объяснение, почему это не хороший выбор:

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

    • Restful веб-сервисы передают информацию метод в метод http.
    • Типично в стиле RPC и SOAP сервисы держать их в сущности-тело и Заголовок http.

    В какой части данных [клиент хочет, чтобы сервер] для работы на является информацию об области действия.

    • Сервисы restful при помощи URI. Мыло/стиля RPC сервисы вновь использовать сущность-тело и заголовки http.

    В качестве примера возьмем Google в Ури http://www.google.com/search?q=DOG. Там, информации, способ GET и информация обзора будет /search?q=DOG.

    Длинная короткая история:

    • В спокойный архитектур, метод, информация идет в http-метод.
    • В Ресурсо-ориентированной архитектуры, данные области идет в URI.

    И правило:

    Если метод http не соответствует информации, способ, сервис не дает отдохнуть. Если данные области не в URI, служба не имеет ресурсную направленность.

    Вы можете поставить "барк" "акция" в URL-адрес (или в лицо-тело) и использовать POST. Никаких проблем нет, он работает, и может быть самый простой способ сделать это, но это не спокойный.

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

    Я не могу говорить о конкретных бизнес-задач, но позвольте мне дать вам пример: рассмотрим службу restful заказ где выполняются заказы на идентификаторы URI, как example.com/order/123.

    Теперь говорят, что мы хотим отменить заказ, как мы собираемся это сделать? Один может возникнуть соблазн думать, что это "отмена" "действие" и оформить его по POST example.com/order/123?do=cancel.

    То есть не спокойный, как мы выше говорили. Вместо этого, мы могли бы PUT новое представление order с canceled элемент отправлены true:

    PUT /order/123 HTTP/1.1 Content-Type: application/xml  <order id="123">     <customer id="89987">...</customer>     <canceled>true</canceled>     ... </order> 

    И вот оно. Если заказ не может быть отменен, определенный код состояния могут быть возвращены. (А ресурс-дизайн, как POST /order/123/canceled с лицом-телом true может, для простоты, также доступны.)

    В вашем конкретном случае вы можете попробовать нечто подобное. Этак, в то время как собака лает, например, GET в /v1/dogs/1/ может включать, что информацию (например, <barking>true</barking>). Или... если это слишком сложно, ослабить свой спокойный требование и придерживаться POST.

    Обновление:

    Я не хочу, чтобы ответ слишком большой, но это занимает некоторое время, чтобы получить повесить выставляя алгоритм (в действии) как совокупность ресурсов. Вместо того, чтобы думать в терминах действия ("делать поиск мест на карте"), надо думать в терминах результатов действий ("список мест на карте, соответствующие критериям поиска").

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

    Переменные запроса представляют информацию об области действия, но делать не обозначают новые ресурсы (/post?lang=en явно же ресурс, как /post?lang=jp просто различные представления). Вернее, они используются, чтобы передать состояние клиента (как ?page=10 так что государство не хранится на сервере; ?lang=en тоже пример здесь) или ввод параметров для алгоритмических ресурсов (/search?q=dogs, /dogs?code=1). Опять же, не отдельных ресурсов.

    Http-команд' (методов) свойства:

    Еще один явный момент показывает, что ?action=something в URI не спокойный, свойства http-команд:

    • GET и HEAD безопасны (и идемпотентной);
    • PUT и DELETE идемпотентные только;
    • POST не является ни.

    Безопасность: В GET или HEAD запрос-это запрос на чтение некоторых данных, а не запрос на изменение любого состояния сервера. Клиент может сделать GET или HEAD запрос 10 раз и это так же, как делает это однажды, или не делать его вообще.

    Idempotence: идемпотентная операция в тот, который имеет тот же эффект, являетесь ли вы применять его один или несколько раз (в математике умножение на ноль идемпотентными). Если вы DELETE ресурс один, опять удаление будет иметь тот же эффект (ресурс GONE уже).

    POST не является ни безопасным, ни идемпотентным. Сделав два одинаковых POST запросы на 'фабрике' ресурсов, вероятно, приведет к двум подчиненным ресурсы, содержащие такую же информацию. С перегруженными (метод в URI или юридическое лицо-тело) POST тады ой.

    Оба эти свойства были важны для успеха протокола http (по ненадежным сетям!): сколько раз вас в курсе (GET) страницу, не дожидаясь, пока он полностью загружен?

    Создание действий и поместив его в URL явно ломает http-методы' договора. В очередной раз технология позволяет, вы можете сделать это, но это не спокойный дизайн.

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

    Такие API, как XMLRPC использовать пост , чтобы вызвать действия, которые может выполнить произвольный код. "Действие" входит в 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 приведен, чтобы показать, что пост-это обычный выбор http-команд для серверных методов. Вот Рой Филдинг мысли о пост - он о многом говорит это спокойным, чтобы использовать http-методы, как указано.

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

    Я отвечала ранее, но этот ответ противоречит мой старый ответ и вытекает много разных стратегии пришли к решению. Он показывает, как http-запрос строится из понятий, которые определяют rest и http. Он также использует PATCH вместо POST или PUT.

    Он проходит через трудности, остальные, затем компоненты http, затем возможное решение.

    Остальное

    Остальное-это набор ограничений, которые должны применяться, чтобы распределенная система гипермедиа, чтобы сделать его масштабируемым. Даже осмыслить его в контексте удаленно контролировать действия, вы должны думать, дистанционно контролируя действия как часть распределенной системы гипермедиа -- часть системы для обнаружения, просмотра и изменения взаимосвязанной информации. Если это больше проблем, чем оно того стоит, то это наверное не хорошо, чтобы попробовать, чтобы сделать его спокойным. Если вы просто хотите "панель управления" графический Тип на клиенте, который может инициировать действия на сервер через 80 порт, то вы, вероятно, хотите простой интерфейс RPC, как json-RPC, а через http-запросов/ответов, или с websocket.

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

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

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

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

    Давайте начнем с первого из ограничений: ресурсов определение.

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

    Так что собака-это ресурс. Он должен быть определенным.

    Точнее, ресурсов Р - это временно различной функции принадлежности МР(Т), который в течение времени т соответствует набор сущностей или значений, которые эквивалентны. Значения в наборе может быть ресурсом представлений и/или идентификаторы ресурсов.

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

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

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

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

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

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

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

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

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

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

    Протокол http

    Протокол http реализует остальные ограничения следующим образом:

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

    ресурс представительства: юридического лица-тела

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

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

    Вы решили на http://api.animals.com/v1/dogs/1 в качестве URI. Допустим, клиент получил от этого какую-то страницу на сайте.

    Давайте использовать эту сущность-тело (стоимость next - это метка времени; значение 0 означает 'при получении первого запроса'):

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

    Теперь нам нужен метод. Патч подходит "части, предназначенные государство" описание мы определились:

    Метод патч просит, что набор изменений, описанных в заявке субъект быть применен к ресурсу, который определен запрос 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 и полезное сообщение почему.

    Это не является необходимым, чтобы отдых для служб в соответствии с графиком лыко в представительстве в ответ на GET /v1/dogs/1/ но это имеет смысл если представление json, было это:

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

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

    POST это http-метод предназначен для

    Обеспечение блок данных...процесса обработки данных

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

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

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

    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 как он это прекрасно можно делать все, что угодно, при соблюдении остальных ограничений.

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

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

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

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

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

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

    Смотрите мой новый ответ - это противоречит этому один и объясняет, rest и http более четко и точно.

    Вот рекомендации , что происходит, чтобы быть спокойным, но, конечно, не единственный вариант. Начинают гавкать, когда служба получает запрос:

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

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

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

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

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

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

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

    Объяснение

    Остальное

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

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

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

    Протокол http

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

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

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

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

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

    Отдых ориентирован ресурс стандартного, это не действие и результат, как в RPC будет.

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

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