Почему целью для спокойного дизайна?

Спокойный принципы принести функций, которые делают веб-сайты легко (на случайная человека пользователя чтобы "Прибой", у них) веб-служб API дизайн, поэтому они удобны для программиста, чтобы использовать. Остальные же'т хорошо, потому что он's отдых, это's хорошо, потому что это's хорошо. и это хорошо, в основном потому, что он является простой. Простота обычный HTTP (без мыла конверты и один-Ури перегружен почтовые услуги), что некоторые могут назвать то"не то", фактически его величайшая сила. С места в карьер, http просит вас адресуемость и безгражданства: две основные конструктивные решения, которые держат на HTTP масштабируемой до сегодня'ы мега-сайты (и мега-услуги). Но остальное не серебро bulltet: иногда RPC-типа (на"удаленный вызов процедур и" - таких, как мыло) может быть уместен, а иногда и другие потребности превалируют над достоинствами паутины. Это нормально. То, что мы не'т действительно, как излишне сложности. Слишком часто программист или компания приносит в стиле RPC-сервисов на работу, что старый добрый http справится просто отлично. Эффект заключается в том, что HTTP не сводятся к транспортным протоколом для огромную полезную нагрузку XML, который объясняет, что'ы "и действительно" не происходит (не Ури или HTTP-метод дать подсказку об этом). В результате служба слишком сложна, невозможно отладить, и выиграл'т работу, если ваши клиенты имеют точная настройка как разработчик. Так же, как в Java/C# код может быть не объектно-ориентированное, просто через HTTP не сделать дизайн спокойный. Может быть догнал в спешке думает о своих услугах в плане действий и дистанционных методов, что следует называть. Неудивительно, что это будет в конечном итоге в стиле RPC сервиса (остальное-ЭКП-гибрид). Первый шаг-это думать иначе. Спокойный дизайн может быть достигнуто многими способами, один из способов (Самый простой, можно сказать) - это думаете ваша заявка в плане ресурсов, а не действий:

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

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

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

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

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

• *(1) дано только обслуживание Ури, как и "случайные" и программист знаю "действие" глагол существует?
• (2) Если программист знает, что он существует, как он узнает, что его семантика? Что это глагол означает?
• (3) Какие свойства (безопасность, idempotence) следует ожидать, что глагол иметь?
• (4) а если программист имеет очень простой клиент, который только обрабатывает стандартных HTTP-заголовков?
• (5) ... Теперь давайте'ы вы можете использовать пост (я'МР обсудим ниже почему, просто поверьте мне на слово сейчас):

POST /v1/dogs/1/ HTTP/1.1
Host: api.animals.com

{"action":"bark"}

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

• {"в действии" и:"и кора" и} документ; и
• `/В1/собак/1/ была "и процессор, документ" и (заводской) Ури. <суб>а "документ процессор" это URI, который вы'd, просто на "кидать" и "забыть" около них - процессор может перенаправить вас на вновь созданный ресурс после того, как на "бросание" по. Е. Г. URI для отправки сообщений на брокера сообщений, которые, после того, как проводка будет перенаправить вас на URI, который показывает статус сообщения'обрабатывать&.ЛТ;/суб> Я не'т много знаю о вашей системе, но я'd уже спорим, как ты'т правда:
• {"в действии" и:"с коры на"} - это не документ, фактически метод ты пытался ниндзя-скрытность в услужение; и
• В /В1/собак/1/ URI-это и "Собака" в ресурсах (наверное собака с ИД==1) и не является документом процессор. Итак, теперь мы знаем, что конструкция выше не столь спокойным, но что именно? **Что в этом плохого?** В основном, это плохо, потому что это сложный Ури со сложными смыслами. Вы можете'т сделать какой-либо вывод из него. Как программист знаю, что собака естькорадействий, которые могут быть незаметно переплетаются спост` в него?

  Конструируя свой вопрос'ы вызовы API

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

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

• Метод пост
• Ресурс /лает, подресурса собаки: /В1/собак/1/лает, представляет гавкать на "фабрике" по. Этот URI является уникальным для каждой собаки (так как он находится под /В1/собак/{ИД}). Теперь каждый случай свой список имеет определенное поведение.

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

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

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

  В этом случае проста. Вызов лает завод ресурс производит коры (электронной почты) и ответ (если ОК или нет) дается сразу: в <предварительно><код>пост /В1/собак/1/лает на HTTP/1.1 Ведущий: api.animals.com Разрешение: базовый mAUhhuE08u724bh249a2xaP= (лицо-тело пустым - или, если требуется документ, разместите его здесь) в <сильный>200 ОК</сильные> </код></пре> Как это записи (изменений) ничего, 200 OK - это достаточно. Это показывает, что все прошло, как ожидалось. <БР>

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

  В этом случае, клиент должен иметь возможность отслеживать кора задач. Тогда кора задача должна быть ресурсом с его's собственное Ури.: в <предварительно><код>пост /В1/собак/1/лает на HTTP/1.1 Ведущий: api.animals.com Разрешение: базовый mAUhhuE08u724bh249a2xaP= {тело документа, в случае необходимости; Примечание: если возможно, ответ должен содержать короткое гипертекстовое примечание с гиперссылкой для вновь созданного ресурса (кора) Ури, то же вернулся в расположение заголовка (также обратите внимание, что код состояния 202, заголовок Location смысл не стандартизированы, таким образом, важность hipertext/ответ гиперссылка)} в <сильный>202 принято Расположение: http://api.animals.com/v1/dogs/1/barks/a65h44</сильный> </код></пре> Таким образом, каждый кора прослеживается. После этого клиент может оформить получить в барк Ури, чтобы знать это'ы текущего состояния. Может быть, даже использовать "удалить", чтобы отменить его. <БР>

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

  Это может быть сложнее, если вы хотите, чтобы позволить клиенту знать "собака" ресурс получает изменен: в <предварительно><код>пост /В1/собак/1/лает на HTTP/1.1 Ведущий: api.animals.com Разрешение: базовый mAUhhuE08u724bh249a2xaP= {документ органа, при необходимости; если это возможно, содержащий hipertext/гиперссылка с адресом в заголовке location -- говорит стандарт} в <сильный>303 увидеть другие Расположение: http://api.animals.com/v1/dogs/1</сильный> </код></пре> В этом случае заголовка location'ы целью является, чтобы позволить клиенту знать, что он должен взглянуть на "собака". Из HTTP в РЧЦ О 303:

  этот метод существует прежде всего, чтобы позволить выход пост-активировать скрипт для переадресации агента пользователя на выбранный ресурс. Если задача асинхронного барк подресурса нужен просто как 1.2 ситуации 303 должны быть возвращены на вам .../лает/г, когда задача будет завершена. <БР>

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

  в <предварительно><код>пост /В1/собак/1/лает на HTTP/1.1 Ведущий: api.animals.com Разрешение: базовый mAUhhuE08u724bh249a2xaP= (тела документа, если требуется) в <сильный>создано 201 Расположение: http://api.animals.com/v1/dogs/1/barks/a65h44</сильный> </код></пре> В здесь, кора - это создается благодаря запросу, поэтому статус создан 201 применяется. Если создание асинхронного 202 принято требуется (поскольку протокол HTTP RFC не написано) вместо этого. Метки Спас является частью ресурса коры и могут быть получены с помощью "получить" его. Обновленный собака может быть "документально" в том, что вам собак/х/лает/г, а также. <БР>

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

  Формулировка эта-сложная, но очень простой асинхронной задачи: в <предварительно><код>пост /В1/собак/1/лает на HTTP/1.1 Ведущий: api.animals.com Разрешение: базовый mAUhhuE08u724bh249a2xaP= (тела документа, если требуется) в <сильный>202 принято Расположение: http://api.animals.com/v1/dogs/1/barks/a65h44</сильный> </код></пре> Затем клиент должен выдать вам В/В1/собак/1/лает/a65h44 знать текущее состояние (если код был разобран, его письмо было отправлено владельцу и такие). Всякий раз, когда собака изменения, 303 является appliable. <БР>

  Закруглялись

  Цитирую Рой Филдинг: единственное, остальное требует методов является то, что они равномерно определенными для всех ресурсов (т. е., Так, что посредники не должны знать тип ресурса для того, чтобы понять смысл По запросу). В приведенных выше примерах, пост равномерно предназначены. Это сделает собаку " игавкатьна". Что это не безопасный (в смысле кора имеет влияния на ресурсы), ни идемпотентом (каждый запрос создает новый кора), который соответствует пост глагол хорошо. Программист будет знать: пост на урожайность лает а барк. Состояние ответа коды (также с лица и тела и заголовков при необходимости) выполнить работу, объясняя, что изменилось и как клиент может и должно происходить. <суб>Примечание: основными источниками были: " ввеб-служб RESTful" в книге HTTP в документе RFC и Рой Филдинг'ы блог.</суб> <БР> <БР>

  Редактировать: Вопрос и соответственно ответ немного изменилось, так как они были впервые созданы. В вопрос спросил про дизайн Ури как:

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

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

• Веб-служб RESTful способ передать данные в метод HTTP.
• Типично в стиле RPC и SOAP сервисы держать их в сущности-тело и заголовок HTTP. Часть данных [клиент хочет, чтобы сервер] для того чтобы работать на это обзорное информации.
• Сервисы RESTful при помощи URI. Мыло/в стиле RPC сервисы в очередной раз использовать сущность-тело и заголовки HTTP. В качестве примера, берем Гугл'ы Ури http://www.google.com/search?q=DOG. Есть информация, метод GET и обзорного информация /поиск?м=собака. Длинная короткая история:
• В RESTful-архитектуры, информационный метод переходит в метод HTTP.
• В ресурсо-ориентированной архитектуры, в обзорном информация идет в Ури. И правило:

  если метод HTTP не соответствует информации, метод, служба не дает отдохнуть. Если информация обзора не в URI, служба не имеет ресурсную направленность. Вы можете поставить то" "и действие на&quot кора" ПО -; в URL-адрес (или в лицо-тело) и использовать пост. Никаких проблем, он работает, и может быть самый простой способ сделать это, но это'т спокойному*. Чтобы держать вашу службу очень спокойный, вы, возможно, придется сделать шаг назад и подумать о том, что вы действительно хотите сделать здесь (какие последствия это будет иметь на ресурсы). Я могу'т поговорить о ваших конкретных потребностей бизнеса, но позвольте мне дать вам пример: рассмотрим службу RESTful заказ где заказы на идентификаторы URI нравится example.com/order/123`. Теперь говорят, что мы хотим отменить заказ, как мы собираемся сделать это? Один может быть склонны думать, что это то"Отмена" по "в действии" - А* и а пост example.com/order/123?do=cancel. Это не спокойный, как мы говорили выше. Вместо этого, мы могли бы "расставить" новое представление "порядок" с отменили элемент отправляются в true:

PUT /order/123 HTTP/1.1
Content-Type: application/xml


    ...
    true
    ...

И что's оно. Если заказ может'т быть отменена, определенный код состояния может быть возвращен. <суп>(дизайн подресурсов, как пост /приказ/123/отменен с лица-тела "истинный" может, для простоты, также доступны.)</SUP и ГТ; В вашем конкретном случае вы можете попробовать нечто подобное. Этак, в то время как собака лает, например,получитьВ/В1/собак/1/может включать эту информацию в <SUP-серфинг>(например, в<лай>правда</лай>)</SUP-серфинг>. Или... если это&#39;s слишком сложная, размять спокойное требование и придерживатьсяпост. Обновление###: Я не'т хотим, чтобы принять ответ слишком большой, но это занимает некоторое время, чтобы получить повесить выставляя алгоритм (в *действие*) как совокупность ресурсов. Вместо того, чтобы думать в терминах действия (*"и делать поиск мест на карте", У*), нужно думать с точки зрения результатов этого действия (*"в список мест на карте, соответствующие запросам критерии и"*). Вы можете найти себе возвращаться к этому шагу, если вы обнаружите, что ваш дизайн не'т подходят для HTTP'ы унифицированный интерфейс. Переменные запроса **являются** *определения объема информации*, но **не** обозначения новых ресурсов (/пост?Ланг=Енявно **же** ресурс/пост?Ланг=ДЖП, просто разное представление). Скорее, они используются для передачи клиента (как?страницы=10, так что государство не хранится на сервере;?Ланг=Ени пример здесь) или **входные параметры** в *алгоритмические ресурсы* (/поиск?м=собаки,/собак?код=1`). Опять же, не отдельные ресурсы.

Команды http' (методов) свойства:

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

• GET и голова являются безопасными (и идемпотентной);
• Класть и delete являются идемпотентными только;
• Пост не является ни. Безопасность: а GET или голова запрос-это запрос на номер чтения некоторые сведения, не просьбой изменить любое состояние сервера. Клиент может сделать GET или голова запрос 10 раз и это'ы то, что делает это однажды, или не делать его вообще. Idempotence: идемпотентная операция в один, что имеет тот же эффект, будете ли вы применять его один или несколько раз (в математике умножение на ноль идемпотентными). Если вы "удалить" ресурс один, опять удаление будет иметь тот же эффект (ресурс "ушел" уже). <суп><суб>пост не является ни безопасным, ни идемпотентным. Сделав два одинаковых пост запросы 'фабрика' ресурсов, вероятно, приведет в двух подчиненные ресурсы, содержащие одинаковые информация. С перегруженными (метод в Ури или юридическое лицо-тело) пост, все ставки выключены.</суб></SUP и ГТ; Оба эти свойства были важны для успеха протокола HTTP (через ненадежные сети!): сколько раз вы обновили ("получить") страницу, не дожидаясь ее полной загрузки? Создание действие* и поместив его в URL явно нарушает методов http' договор. В очередной раз технология позволяет, Вы можете сделать это, но это не спокойный дизайн.

Я ответил ранее](https://stackoverflow.com/a/16997574/972499), но этот ответ противоречит мой старый ответ и последует много разных стратегия для решения. Он показывает, как HTTP-запрос строится из понятий, которые определяют REST и HTTP. Он также использует патч вместо пост или положить. Он проходит через трудности остальное, то компоненты http, то возможным решением.

Отдых #

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

определение ресурсов; манипулирование ресурсами через представления; описательные сообщения; и, гипермедиа как двигатель состояние приложения. Вы спросите, как можно определить интерфейс, встречи эти ограничения, с помощью которых один компьютер говорит другим компьютером, чтобы сделать собачий лай. В частности, вы хотите, чтобы ваш интерфейс должен быть HTTP, а вы Дон'т хотим, чтобы отказаться от возможности, что сделать HTTP-спокойный, когда используется по назначению. Позвольте's начинает с первых ограничения: определение ресурсов. любая информация, которая может быть названа может быть ресурс: документ или изображение, временной услуги (например, на "Сегодня'ы погода в Лос-Анджелесе и"), коллекция других ресурсов, а не виртуальный объект (например, человека), и так далее. Так что собака-это ресурс. Он должен быть идентифицирован. точнее, ресурс <и>Р</а> это временно различной функции принадлежности <и>м<суб>Р</суб></я и GT;(<и>Т&Л;/Я и GT;), что для времени <и>Т&Л;/Я и GT; карты с набором объектов или значений, которые эквивалентны. Значения в наборе может быть resource representations и/или resource identifiers. Вы model собака с набором идентификаторов и представлений и говорю, что они все связаны друг с другом в данный момент времени. А теперь давайте's используйте идентификатор и"Собака #1" по. Это приводит нас ко второму и третьему ограничения: представления и о себе. остальные компоненты выполняют действия на ресурсе, используя представление для захвата текущего или предполагаемого состояния ресурсов и передачи, что представление между компонентами. Представление-это последовательность байт, плюс метаданные представления для описания этих байтов. Ниже приводится последовательность байтов захват предполагаемого состояния собаки, т. е. в представлении мы хотим быть связаны с идентификатором "у собаки #1", которая (обратите внимание, что это только часть государства, как это не пес's имя, здоровье, или даже последние лает): Это был лай каждые 10 минут с момента времени, когда это состояние изменение было произведено, и будет продолжаться бесконечно. Это должны быть прикреплены к метаданные, которые описывают его. Эти метаданные могут быть полезны: Это английская инструкция. Он описывает часть предполагаемого состояния. Если он получил несколько раз, только первый эффект. Наконец, позвольте's взглянуть на четвертом ограничения: HATEOAS. В остальном ... виды аппликации как целостной структуры информации и альтернатив управления, благодаря которой пользователь может выполнить нужную задачу. Например, просмотр-слово в онлайн-словарь одном приложении, а гастроли через виртуальный музей, или пересматривают набор класса ноты готовиться к экзаменам. ... Следующего государственного контроля приложение размещается в представительстве первого запрошенного ресурса, т. е. получение, что первое представление является приоритетным. ... Поэтому модель приложения-это механизм, который переходит из одного состояния в другое, рассматривая и выбирая среди альтернативных состояния в текущий набор представлений. В спокойный интерфейс, клиент получает представление ресурса для того, чтобы выяснить, как он должен получать или отправлять представление. Там должно быть представительство где-то в приложении, из которого клиент может выяснить, как получить или отправить все заявления должны быть в состоянии получить или отправить, даже если он следует за цепь представлений, чтобы прибыть в эту информацию. Это кажется достаточно простым: Клиент просит для представления ресурса, идентифицированного в качестве домашней страницы; в ответ, он получает представление, которое содержит идентификатор каждой собаке клиент может потребоваться. Клиент извлекает идентификатор из его и спрашивает, как он может взаимодействовать с выявленными собака, и говорит-службе клиент может отправить английское заявление с описанием часть предполагаемого состояния собаки. Затем клиент отправляет такое заявление и получает сообщение об успешном или сообщение об ошибке.

Протоколу HTTP #

Протокол HTTP реализует остальные ограничения следующим образом: определение ресурсов: Ури представление ресурса: лицо-тело самоописания: способ или код состояния, заголовки, и, возможно, части лица и тела (например, Ури XML-схемы) HATEOAS: гиперссылки Вы'ве принято решение о http://api.animals.com/v1/dogs/1 как Ури. Позвольте'ы предположим, клиент получил от этого какую-то страницу на сайте. Позвольте's используйте этот орган тела (значениерядом- это метка времени; значение0` означает 'когда этот запрос поступит'):

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

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

метод патч просит, что набор изменений, описанных в заявке субъект быть применен к ресурсу, идентифицированный URI в запросе. И некоторые заголовки: Чтобы указать язык сущности-тело: тип контента: приложение/JSON Чтобы убедиться, что это происходит только один раз: если-без изменений-так: <дата/время это был первый послал> И у нас есть просьба:

PATCH /v1/dogs/1/ HTTP/1.1
Host: api.animals.com
Content-Type: application/json
If-Unmodified-Since: 
[other headers]

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

В случае успеха, клиент должен получить 204 код состояния в ответе, или 205, если представительство /В1/собак/1/ был изменен, чтобы отразить новое расписание лаять. В случае неудачи, он должен получать 403 и полезное сообщение почему. Это не является необходимым, чтобы отдых для служб в соответствии с графиком лыко в представительстве в ответ на получить /В1/собак/1/, но это имеет смысл если представление JSON включил это:

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

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

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

API-интерфейсы, такие как [файла xmlrpc][1] использовать пост, чтобы вызвать действия, которые можно выполнить произвольный код. В "действий" и входит в 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"?>

   examples.getStateName
   <params>
      <param>
         41

Пост - это HTTP метод предназначен для

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

Серверные методы обработки номера-твар-сопоставляется действия является то, что [Рой Филдинг призвано][2] с остальными, так что вы'ре хорошо там, и что's, почему пост был создан, чтобы быть идемпотентными. Пост будет работать с большинством размещение данных на стороне сервера, методами обработки информации.

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

[2]: http://www.ics.uci.edu/~документы Тейлор//2002-остальное-Туа.формат PDF

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

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

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

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

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

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

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

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

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

не'т применять! поэтому игнорировать его.

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

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

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

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

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

Всякий раз, когда вы `сделать /В1/собак/1/кора- "графика", вы должны сделать что-то вроде этого, где в том время последнего кору и ли это интерес + 10 минут:

{с"Последнее": Т "Следующий" У: у}

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

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

Объяснение

Отдых

<ИМГ src="https://docs.google.com/drawings/d/1evznBzXZGY-wBFWoIRTlSjSBkMVbjESBN9EegpC9Osg/pub?w=400">

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

Позвольте'говорят, что факт-это собака. Вы случайно выявить факт как /В1/собак/1. (В значении /В1/собак/1 является членом сможешь.) Что's просто один из многих способов, вы могли бы определить сможешь. Вы могли бы также определить факт в качестве /В1/собак/1/Х-лучей и как `/В1/Руфуса.

Как вы представляете факт? Возможно, с фотографией. Может быть, с набором рентгеновских лучей. Или, может быть, с указанием даты и времени, когда сможешь последний гавкнул. Но помните, что все эти представления библиотеки же resource_. `/В1/собак/1/Х-лучи-это идентификатор одного и того же ресурса, что представляет собой ответ на вопрос "Когда же факт-последние кору?&и"

По HTTP

<ИМГ src="https://docs.google.com/drawings/d/1agqRRpqYyrvXdYuqcilck5tGM1XmmOuLSiNad6VmwsM/pub?w=400">

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

По крайней мере, это's что вам делает. "Пут" - это в основном обратное вам вы положить на факт представления в URL-адрес, если вы хотите, чтобы в будущем "получить" запросы на URL-адрес, чтобы вернуться сможешь, с некоторыми возможными переводами, как JSON в HTML.

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

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

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

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

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

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