Реализуясь с REST

Question

Я разыскиваю приличный пример простого, полностью REST API, но безрезультатно. Проверено также на stackoverflow. Лучшее, что я видел, это это сообщение . Несмотря на это, я все еще не понимаю. Давайте рассмотрим пример приложения, которое мы все знаем: wikipedia.

Предположим, мы хотим создать REST API для Википедии. Мы ожидаем следующих глаголов:

GET /wiki/Article_name: obtains a specified page
DELETE /wiki/Article_name: deletes the page
POST /wiki/Article_name: creates a new page
PUT /wiki/Article_name: updates a page.

Факт: когда вы используете википедию со своим браузером, вы не используете интерфейс REST для навигации по нему. Я почти уверен, что когда вы обновляете страницу, вы никогда не используете PUT (хотя технически вы создаете новую ревизию страницы, поэтому POST имеет смысл). Точно так же, когда вы удаляете страницу, браузер не отправляет УДАЛИТЬ.

Мои вопросы:

• REST - это тоже интерфейс "для браузера" или только для скриптов?
• Должны ли мы видеть мир HTTP исключительно глазами REST-представления? такие вещи, как GET / foo /? page = bar & action = delete, все еще являются верной точкой зрения, или ужасные ошибки прошлого никогда не повторятся?
• должен ли веб-доступ и интерфейс REST смешиваться или разделяться? Например, предположим, что у вас есть приложение AddressBook. Вы можете просматривать адресную книгу с помощью GET / people /, а с помощью GET / people / 1523 вы можете получить эту информацию о единственном человеке в браузере, возможно, в удобном формате для печати. Если вы хотите изменить его карту, вы должны сделать (RESTfully) PUT / people / 1523, или вместо этого сделать как PUT /api/v1.0/people/1523?
• Может ли кто-нибудь убедить Роя Филдинга найти человека и привести пример "5-летнего ребенка" для достойного (по его мнению) API REST, вместо того, чтобы жаловаться на то, что не является RESTful (в его мнение), чтобы весь мир мог довести до конца?

Answer 1

EDIT1: Как я понимаю, для большинства программистов REST как концепция будет рассматриваться при создании API. Таким образом, REST находится в вашем списке дел, когда вы создаете API для потребления на машинах ; НЕ когда вы говорите о веб-страницах, с которыми люди будут взаимодействовать через браузер. EDIT2: И это не значит, что браузер не RESTful (так оно и есть). Я просто имею в виду, что где текущее действие, где большинство программистов мира (те, кто не работает на производителя браузеров) могут извлечь выгоду из REST, в основном в веб-сервисах.

Давайте рассмотрим пример приложение, которое мы все знаем: википедия.

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

GET / wiki / Article_name: получает указанную страницу

DELETE / wiki / Article_name: удаляет страницу

POST / wiki / Article_name: создает новую страницу

PUT / wiki / Article_name: обновляет страницу.

Ваша структура данных основана на модели использования человеком Википедии, отсюда и путаница.

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

Примечание 1: В приведенном ниже примере API я использую JSON. Что касается "RESTfulness", это не обязательно должен быть JSON, любой формат данных, который может быть содержательно обмениваться через HTTP, подойдет. Другими примерами могут быть XML, TXT, JPEG, AVI. В широком смысле «RESTfulness» применяется к заголовкам URL и HTTP, а не к телу страницы - тело остается свободным для конкретных нужд реализации.

Примечание 2: Я притворяюсь, что в Википедии есть внутренний, структурированный формат данных, который преобразуется в HTML-страницы - просто для иллюстрации моего взгляда, поскольку Википедия на самом деле не самая лучшая пример работы с ...

Первый выстрел в RESTful API для Википедии может выглядеть примерно так:

api.wikipedia.com / поиск / ключевые слова

Принимает GET с поисковыми словами в URL, возвращает набор данных JSON с идентификаторами страниц , заголовками страниц, URL-адресами и оценками релевантности.

api.wikipedia.com / статьи / ID /

Принимает GET, DELETE, POST, PUT и обрабатывает статью с внутренним идентификатором, равным «id» в URL. В зависимости от метода HTTP запроса, он будет:

1. GET; возврат статьи (в предопределенном формате данных на основе JSON в Википедии)
2. DELETE; удалить статью
3. POST; создать новую статью (статья должна быть в теле запроса в предопределенном формате JSON)
4. PUT; обновить статью (и вся страница должна быть отправлена ​​заново в теле)

api.wikipedia.com / СМИ / ID /

Как указанная выше конечная точка «article», но для CRUD медиа, таких как изображения. .. и так далее, пока не будут удовлетворены все потребности этого воображаемого API Википедии.

Быстрый взгляд на воображаемый API, приведенный выше, обнаруживает ряд проблем ... и в этом прелесть REST; это просто и не мешает визуализировать обмен данными.

REST также интерфейс "для браузер "или просто для скриптов?

РЕДАКТИРОВАТЬ3 Первоначальный текст был: Он не предназначен для браузера, он предназначен только для API, предназначенных для использования другими клиентами или службами, которые являются «машинами».

Я хотел бы изменить это на: Браузер RESTful. Это также является данностью, то есть с установленной базой и тем, сколько времени требуется для замены IE6, ясно, что браузеры, которые у нас есть сегодня, будут с нами долгое время. А современные браузеры ничего не делают со специальными микроформатами или сайтами с XHTML для воспроизведения страниц и XHTML для передачи данных, они оставляют все это на ваше усмотрение с помощью Javascript.

Таким образом, при использовании современных технологий большая часть новой разработки, в которой применяется REST, заключается в создании более совершенных API веб-служб. А практические соображения заставят людей выбирать API своих веб-сервисов по URL, отличному от основного сайта.

По сравнению с другими технологиями веб-сервисов REST обладает значительным преимуществом в простоте отладки. Вы можете просто запустить клиент на своем ПК, отправить URL-адрес и сразу увидеть ответ. (Хорошо, то же самое относится в некоторой степени ко многим веб-сервисам на основе XML; но сгенерированный компьютером XML нецелесообразно для меня «читать».)

должны ли мы видеть мир HTTP исключительно глазами REST-представления?

Эхх, нет. Браузер обрабатывает 97% трафика сегодняшнего веб-сайта в среднем?

должен ли веб-доступ и интерфейс REST смешиваться или разделяться?

Отдельно, в приведенном выше примере я использовал api.wikipedia.com , чтобы показать, что он полностью отделен от обычного сайта Википедии. Из практических соображений, таких как распределение нагрузки, разные графики выпуска, разные бизнес-требования.

Answer 2

REST также интерфейс "для браузер "или просто для скриптов

Оба. На самом деле Browser - отличный пример REST-клиента. Тот факт, что он использует только подмножество интерфейса HTTP, не нарушает ограничения унифицированного интерфейса. Во всяком случае, POST в значительной степени является групповым глаголом. Сценарии определены в описании REST как «загрузка кода» и играют неотъемлемую часть интерфейса REST.

Обновление: Равномерное ограничение интерфейса REST не говорит "вы должны использовать все доступные глаголы", чтобы быть RESTful. В нем говорится, что если вы используете глагол, используйте его для выполнения действия, которое соответствует ожидаемому поведению.

мы должны увидеть мир HTTP исключительно глазами ОТДЫХА представление

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

Запрос GET /foo/?page=bar&action=delete нарушает правила HTTP и, следовательно, нарушает ограничение REST универсального интерфейса. Но это сначала нарушает HTTP!

Обновление: В спецификации HTTP RFC 2616, раздел 9.1.1, говорится: «В частности, установлено, что методы GET и HEAD НЕ ДОЛЖНЫ иметь значение действия, отличного от извлечения». Выполнение действия удаления с использованием GET определенно нарушает правила HTTP.

должен веб-доступ и ОТДЫХ Интерфейс должен быть смешанным или отдельным?

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

Если вы планируете использовать HTML-интерфейс, почему один и тот же работает дважды?

Может Рой дать нам простой образец?

Прочтите статью Как получить чашку кофе , чтобы получить представление о том, как должен работать REST API.

Читая статью, помните этот важный факт, который, кажется, все забыли:

REST-интерфейсы должны быть ЛЕГКО ИСПОЛЬЗОВАТЬ , они НЕ ЛЕГКО ДИЗАЙН .

Answer 3

Частичный ответ:

Являются ли такие вещи, как GET / foo /? Page = bar & action = delete, по-прежнему действительной точкой зрения, или ужасные ошибки прошлого никогда не повторятся?

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

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

Если вы хотите иметь кнопку удаления, используйте кнопку удаления. Если вы действительно хотите, чтобы кнопка выглядела как ссылка, используйте javascript, чтобы щелкнуть ссылку, чтобы выполнить публикацию (или сделать ссылку ПОЛУЧИТЬ страницу подтверждения, что полностью приемлемо).

Answer 4

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

Является ли REST также интерфейсом "для браузера" или только для скриптов?

Когда вы просматриваете Википедию с помощью Firefox, вы управляете клиентом REST. Отсутствие поддержки PUT и DELETE не умаляет RESTfullnes взаимодействия, поскольку значение HTTP-глаголов выходит за рамки REST. Более сомнительным моментом может быть то, как сайты и браузеры поддерживают сеансы. Когда каждый запрос должен быть понят в контексте сеанса, вы можете сказать, что ограничение запросов без сохранения состояния нарушено.

Должны ли мы видеть мир HTTP исключительно глазами REST-представления? такие вещи, как GET / foo /? page = bar & action = delete, все еще являются верной точкой зрения, или ужасные ошибки прошлого никогда не повторятся?

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

должен ли веб-доступ и интерфейс REST смешиваться или разделяться? Например, предположим, что у вас есть приложение AddressBook. Вы можете просматривать адресную книгу с помощью GET / people /, а с помощью GET / people / 1523 вы можете получить эту информацию о единственном человеке в браузере, возможно, в удобном формате для печати. Если вы хотите изменить его карту, вы должны сделать (RESTfully) PUT / people / 1523, или вместо этого сделать как PUT /api/v1.0/people/1523?

Я не вижу проблемы с RESTful API, работающим по-разному для браузеров и других клиентов REST. Самое главное - обеспечить согласованное поведение в классе клиентов. Управление версиями API выходит за рамки REST.

Может ли кто-нибудь убедить Роя Филдинга найти человека и привести пример "5-летнего ребенка" для достойного (по его мнению) API REST, вместо того, чтобы жаловаться на то, что не является RESTful (по его мнению), чтобы все мир может проследить?

Именно так я себя чувствовал после прочтения этого поста и столкновения с почти полным отсутствием реальных примеров.

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

Забавно, насколько трудно доказать, что эта простая идея попрактиковалась для клиентов, не являющихся браузерами. Для вдохновения вы можете обратиться к Sun Cloud API .

Answer 5

Вы впитываете это.

Да, GET, PUT, POST и DELETE - все вызовы RESTful. Большую часть времени вы используете GET или POST. При переходе по URL-адресу на веб-сервер отправляется запрос GET. Когда вы отправляете форму, это может быть GET или POST, в зависимости от элемента. Тем не менее, DELETE и PUT являются совершенно допустимыми вызовами при правильных обстоятельствах, таких как WebDAV. Страница HTTP может убрать часть этого.

REST для 5-летнего ребенка означает просто «Клиент отправляет серверу запрос на изменение состояния (добавление / замена / удаление / извлечение некоторого содержимого, в случае HTTP), и сервер отвечает (возможно, доставки контента и статуса, возможно, только статуса), и разговор заканчивается. Бесконечного разговора нет. Таким образом, почти ЛЮБОЙ нормальный вызов веб-сервера является RESTful, будь то из вашего браузера, из JavaScript или от telnetting на порт 80 из терминальной программы.

REST обычно используется в отличие от SOAP, где веб-служба имеет возможность описывать себя и свой API-интерфейс для клиента, а веб-службы можно обнаружить из каталогов. Это намного сложнее. Поэтому, по большей части, если вы не используете SOAP (а мыло настолько сложное, что вы не сможете этого сделать, не зная об этом), вы делаете REST.

Пока я обращаюсь к контрастам, некоторые модные словечки будут противопоставлять REST AJAX. Они полностью ортогональны, и вполне возможно использовать методы AJAX для выполнения запросов REST или SOAP. AJAX, для 5-летнего ребенка, просто означает, что какое-то программное обеспечение работает в браузере (это может быть JavaScript, но может быть также Java или Flash), делает HTTP-запрос к серверу и обрабатывает ответ, а не сам браузер поэтому отображение не меняется до тех пор, пока клиентская программа, запущенная в браузере, не решит изменить DOM отображаемой в данный момент страницы.

Что касается ваших вопросов о том, является ли GET хорошей идеей или нет, «это зависит». GET помещает весь запрос в строку запроса. Это означает, что если пользователь хочет выполнить запрос еще раз (скажем, это страница поиска или ссылка на конкретное сообщение в блоге), его можно добавить в закладки. Недостатком является то, что строка запроса может быть очень длинной, и это может привести к тому, что пользователи будут добавлять в закладки те части URL, которые они не должны делать. POST, с другой стороны, может отправлять практически неограниченный контент, но вы не можете добавить его в закладки или отправить URL другу (или врагу, в зависимости от ссылки). Вы должны использовать правильный для ситуации. Иногда вам нужен Philips, иногда вам нужна плоская головка.

Ваш пример с GET / people / 1523 и PUT / people / 1523 совершенно верен, хотя его трудно сделать с обычным веб-сервером, который не поймет, что вы хотите от PUT. "люди" должны были быть программой на каком-то серверном языке, которая могла бы обрабатывать запрос. Если вы используете сервлеты Java, он может быть сопоставлен с сервлетом с любым именем. Было бы намного проще отделить ваш глагол HTTP-запроса от глагола операции с данными, например, GET / people / 1523 / get и POST / people / 1523 / update (или GET / people / get / 1523 и POST / people / update / 1523).

Answer 6

Некоторые современные браузеры по-прежнему не могут отправлять HTTP-запросы, кроме GET и POST. Это блокирует более широкое принятие REST. Хотя некоторые обходные пути для браузеров доступны (см. эту презентацию Дэвида Хайнемайера Ханссона).

По словам Тима Бернерса-Ли, URL-адреса должны быть непрозрачными (хотя здесь есть некоторые споры ), поэтому такие вещи, как GET /foo/?bar=baz HTTP/1.1, в порядке, поскольку GET остается идемпотентным и безопасным. 1011 *

Повторное использование URL-адресов при доступе к ним с различными типами мультимедиа считается хорошей практикой.

Я думаю, что можно использовать RFC 5023 Протокол публикации Atom в качестве канонического примера RESTful API (по крайней мере, Рой Филдинг прокомментировал некоторые связанные с этим вопросы).

Answer 7

• NerdDinner.com ¹
• API Sun Cloud
• Twitter
• статья Пола Джеймса
• API MediaWiki ²

<ч /> 1. NerdDinner использует службы данных WCF, что является отличным способом для правильной реализации служб RESTful. Причина, по которой я указываю на это, а не на службы данных WCF, заключается в том, что это общедоступный веб-сайт, и вы можете им пользоваться. 2. MediaWiki не является хорошим примером, потому что они передают действия в URI, но технически это сервис RESTful и показывает много интересных идей.