Написание клиента для API RESTful (гипермедиа)

Я читаю "настоящие" API RESTful уже несколько дней, и я думаю, что я близок к тому, чтобы разобраться в этом.

Но одна из вещей, которые я натыкаюсь, - это то, что я даже не могу представить, как написать клиент для "реального" гипермедиа API:

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

  • Одна вещь, которая не ясна для меня, заключается в том, как клиент знает, какой глагол использовать на какой-либо данной ссылке? Является ли это подразумеваемым в "rel" типе uri? Альтернатива (чтение здесь), кажется, использует xhtml и имеет клиента, который может анализировать и публиковать формы.

  • Насколько вероятно, что ссылка изменится, но не маршрут к ссылке? В большинстве примеров вы видите вокруг, маршрут и ссылка одинаковы:

например. если я хочу настроить клиента, который вернет мне список тортов из Toni Cake Shop:

http://tonis.com
{ link: { type : "cakes" ; uri : "http://tonis.com/cakes" } }

Что происходит, когда Тони становится продуктовым магазином Тони, а ссылка становится http://tonis.com/desserts/cakes?

Сохраняем ли начальную ссылку cakes в корне, для обратной совместимости? А если нет, то как мы делаем "перенаправление" для бедного маленького агента, которому было сказано "идти корнем, искать пирожные"?

Что мне не хватает?

Ответы

Ответ 1

@Benjol

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

Я бы изменил ваш пример следующим образом:

{"link": {
  "rel":   "collection http://relations.your-service.com/cakes",
  "href":  "http://tonis.com/cakes",
  "title": "List of cakes",
  "type":  "application/vnd.yourformat+json"
}}

если есть клиент, который потребляет ваш сервис, он должен понимать:

  • сама структура ссылок
  • (в данном случае "сбор", который является RFC и " http://relations.your-service.com/cakes", который является вашим доменом конкретная связь)

В этом случае клиент может просто указать адрес разыменования, указанный атрибутом "href", и отобразить список тортов. Позже, если вы измените клиент URI поставщика торта, он продолжит работу, это означает, что клиент все еще понимает семантику вашего типа медиа.

P.S.

Ответ 2

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

Прежде всего, вы не можете избежать первоначального соглашения между клиентом и сервером, цель REST состоит в том, чтобы заставить их согласиться с минимальным количеством вещей, которые имеют отношение к обоим из них, и пусть каждая сторона заботится о них собственные вещи сами. Например, клиент не должен заботиться о макете ссылок или о том, как данные хранятся на сервере, а серверу не нужно заботиться о состоянии клиента. То, что они соглашаются заранее (то есть до начала взаимодействия), - это то, что назвали авторы книги "Domain Application Protocol" (DAP).

Важная вещь в DAP заключается в том, что он является работоспособным, хотя сам HTTP не является (поскольку любое взаимодействие с клиентом и сервисом имеет состояние, по крайней мере, начинается и заканчивается). Это состояние можно описать в терминах "Что клиент может/может/должен делать дальше": "Я начал использовать службу, что теперь? Хорошо, я могу искать элементы. Поиск этого элемента, что дальше?, Я могу заказать то-то и то... и т.д."

Определение типа содержимого Hypermedia позволяет обрабатывать как обмен данными, так и состояние взаимодействия. Как я уже упоминал, состояние описывается с точки зрения возможных действий, и, как это происходит из "Ресурса" в REST, все действия описываются с точки зрения доступных ресурсов. Я думаю, вы видели акроним "HATEOAS (Hypermedia как двигатель состояния приложения), так что, по-видимому, это означает.

Итак, чтобы взаимодействовать с сервисом, клиент использует формат гипермедиа, который они оба понимают, который может быть стандартным, доморощенным или смесью тех (например, на основе XML/XHTML). В дополнение к этому, они также должны использовать протокол, который, скорее всего, HTTP, но поскольку некоторые детали не указаны в стандарте, должны быть некоторые идиомы его использования, такие как "Использовать POST для создания ресурса и PUT для обновления", Кроме того, такой протокол будет включать точки входа службы (опять же, с точки зрения доступных ресурсов).

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

Ответ 3

После просмотра этого видеозаписей Джона Мура у меня было намного лучшее понимание гиперссылки apis http://oredev.org/2010/sessions/hypermedia-apis