Заключается в том, что API-интерфейс REST, действительно ЭКП? Рой Филдинг, кажется, так думает

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

из первого абзаца API REST должны быть гипертекстовыми, это довольно ясно, что он считает, что его работа широко истолковали:

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

Филдинг продолжает перечислять несколько атрибутов API-интерфейса REST. Некоторые из них, похоже, идут вразрез как с обычной практикой, так и с общими советами на SO и других форумах. Например:

  • A REST API должен быть введен без каких-либо предварительных знаний, кроме начального URI (закладки) и набора стандартных типов носителей, которые подходят для целевой аудитории (т. е., как ожидается, будут поняты любым клиентом, который может использовать API). ...

  • API REST не должен определять фиксированные имена ресурсов или иерархии (очевидная связь клиента и сервера). ...

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

идея "гипертекста" играет центральную роль - гораздо больше, чем структура URI или что означают http-глаголы. "Гипертекст" определяется в одном из комментариев:

когда я [Филдинг] говорю гипертекст, я имею в виду одновременное представление информации и управляет таким образом, что информация становится доступностью, через которую пользователь (или автомат) получает выбор и выбирает действия. Гипермедиа - это просто расширение того, что означает текст для включения временных якорей в поток медиа; большинство исследователей отбросили это различие.

гипертекст не должен быть HTML в браузере. Машины могут переходить по ссылкам, когда они понимают формат данных и типы отношений.

Я думаю в этот момент, но первые два пункта выше, по-видимому, предполагают, что документация API для ресурса Foo, которая выглядит следующим образом, приводит к тесной связи между клиентом и сервером и не имеет места в спокойной системе.

GET   /foos/{id}  # read a Foo
POST  /foos/{id}  # create a Foo
PUT   /foos/{id}  # update a Foo

вместо этого агент должен быть вынужден обнаружить URI для всех Foos, например, выдав запрос GET против /foos. (Эти URI могут оказаться следующими схеме выше, но это не имеет значения.) В ответе используется тип носителя, который способен передавать как получить доступ к каждому элементу и что с ним можно сделать, давая начало третьему пункту выше. По этой причине документация API должна сосредоточиться на объяснении того, как интерпретировать гипертекст, содержащийся в ответе.

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

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

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

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

Итак, два простых вопроса для остальных экспертов там с a практическое мышление: как вы интерпретируете то, что говорит Филдинг, и как вы применяете его на практике при документировании/реализации API REST?

Edit: этот вопрос является примером того, как трудно может быть узнать что-то, если у вас нет названия для того, о чем вы говорите. Название в данном случае - "гипермедиа как движок состояния приложения" (HATEOAS).

9 92
database-restore hateoas

9 ответов:

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

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

Если вы документируете URI или как чтобы построить их, вы делаете это неправильно.

19

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

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

8

Я искал хороший пример API, написанный после HATEOAS, и не смог его найти (я обнаружил, что как API SunCloud, так и atompub трудно применить к "нормальной" ситуации API). Поэтому я попытался сделать реалистичный пример в своем блоге, который следовал совету Роя Филдинга о том, что значит быть правильной реализацией отдыха. Мне было очень сложно придумать пример, несмотря на то, что он довольно прост в принципе (просто запутывает при работе с API в отличие от веб-страницы). Я понимаю, с чем Рой столкнулся и согласен, это просто сдвиг в мышлении, чтобы правильно реализовать API.

посмотреть: пример API с использованием Rest

5

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

некоторые хорошие дискуссии об отдыхе и связанных с ним HATEOAS:

преимущества (также) использования HATEOAS в RESTFul APIs

как получить чашку кофе

4

для тех, кто заинтересован, я нашел подробный пример HATEOAS на практике в Sun Cloud API.

4

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

4

абсолютно правильно. Кроме того, я бы отметил, что шаблоны URI отлично подходят для приложения RESTful, если шаблоны получены из документов, полученных с сервера (OpenSearch является подходящим примером). Для шаблонов URI вы документируете, где они используются и каковы ожидаемые заполнители в шаблоне, но не сами шаблоны. Немного вопреки тому, что сказал Ванфриден, это не исключение.

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

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

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

1

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

согласно модели зрелости Ричардсона, есть 4 уровня (0-3), которые определяют, насколько RESTful ваш API, причем 3 означает действительно RESTful API, как и предполагал Рой Филдинг.

Уровень 0, когда у вас есть одна точка входа URI - как мыло.

Уровень 1 означает, что API способен чтобы различать разные ресурсы, и имеет не одну точку входа - все равно пахнет мылом.

Уровень 2-это когда вы используете http - глаголы-GET, POST, DELETE в первую очередь. Это уровень, на котором отдых действительно входит в картину.

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

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

1

предположим GET /foos/createForm вызывается, чтобы получить значения полей формы, для которых должны быть обеспечены, когда мы идем, чтобы создать POST /foos . Теперь этот конкретный URL-адрес, т. е. 1, используемый для создания foos, должен быть упомянут в ответе для GET /foos/createForm Как отправить ссылку действия в соответствии с предложением Филдинга, верно ?
Тогда в чем преимущество сопоставления действий с известными http-глаголами для действий, "соглашение над кодом/конфигурацией" вещь обнуляется.

0