Обнаружение среды выполнения RESTful API / дизайн клиента HATEOAS

Question

Для запуска SaaS, в котором я участвую, я создаю веб-API RESTful и несколько клиентских приложений на разных платформах, которые его используют. Я думаю, что я выяснил API, но теперь я обращаюсь к клиентам. Когда я читал о REST, я вижу, что ключевой частью REST является discovery , но, похоже, существует много споров между двумя различными интерпретациями того, что на самом деле означает открытие:

1. Обнаружение разработчика : разработчик жестко кодирует в клиенте большое количество деталей API, таких как URI ресурса, параметры запроса, поддерживаемые методы HTTP и другие подробности, обнаруженные ими просматривая документы и экспериментируя с ответами API. Этот тип обнаружения IMHO требует интересного связывания и вопроса о версии API и приводит к жесткой связи клиентского кода с API. Кажется, не намного лучше, чем при использовании хорошо документированной коллекции RPC.

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

Обнаружение во время выполнения, похоже, является святым Граалем REST, но я вижу очень маленькую дискуссию о том, как реализовать такого клиента. Кажется, почти все источники REST, которые я нашел, предполагают обнаружение разработчика Кто-нибудь знает о некоторых ресурсах обнаружения времени выполнения? Лучшие практики? Примеры или библиотеки с реальным кодом? Я работаю в PHP (Zend Framework) для одного клиента. Objective-C (iOS) для других.

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

Answer 1

В этом видео Джон Мур строит общий клиент, используя автообнаружение HATEOAS во время выполнения.Это довольно впечатляюще и стоит посмотреть:

http://oredev.org/oredev2010/2010/sessions/hypermedia-apis.html

Answer 2

Это определенно крепкий орешек. В Google мы внедрили наш Discovery Service, на котором созданы все наши новые API. Версия TL; DR - мы генерируем спецификацию JSON-схемы, которую могут анализировать наши клиенты - многие из них динамически.

Полученные результаты означают более простые обновления SDK для разработчика и более легкое / качественное обслуживание для нас.

Отнюдь не идеальное решение, но многим нашим разработчикам это нравится.

См. ссылка для получения более подробной информации (и обязательно посмотрите видео.)

Answer 3

Захватывающий. То, что вы описываете - это принцип HATEOAS. Что такое HATEOAS, спросите вы? Читать это: http://en.wikipedia.org/wiki/HATEOAS

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

Answer 4

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

UDDI рассказывает острую историю открытия во время выполнения: http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration

Answer 5

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

Теперь предположим, что у нас есть HTTP / JSON API для интернет-магазина, и мы хотим создать клиент HTML / CSS / JavaScript, который предоставит нашим клиентам превосходный пользовательский интерфейс. Будет ли реалистичным вариант, чтобы этот клиент был универсальным клиентским приложением? Нет. Мы хотим предоставить конкретный внешний вид для каждого конкретного элемента данных и каждого конкретного состояния приложения. Мы не хотим включать все знания об этих особенностях представления в API, напротив, клиент должен определять внешний вид, а API должен только переносить данные. Это подразумевает, что клиент имеет жестко запрограммированную привязку определенных элементов ресурса к конкретным макетам и взаимодействиям с пользователем.

Это конец HATEOAS и, следовательно, конец REST? Да и нет .

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

Нет , по двум причинам:

1. Быть "RESTful" является свойством API, а не клиента. Если это возможно, в теории , для создания универсального клиента, который предлагает все возможности API, API можно назвать RESTful. Тот факт, что клиенты не подчиняются правилам, не является ошибкой API. Тот факт, что у общего клиента будет паршивый пользовательский опыт, не является проблемой. Почему важно знать, что возможно иметь универсального клиента, если у нас на самом деле нет этого универсального клиента? Это подводит меня ко второй причине:
2. RESTful API предлагает клиентам возможность выбрать, какими универсальными они хотят быть, то есть насколько они устойчивы к изменениям на стороне сервера, которые они хотят. Клиенты, которым необходимо обеспечить удобство работы с пользователями, могут по-прежнему быть устойчивыми к изменениям URI, изменениям значений по умолчанию и многим другим. Клиенты, выполняющие пакетные задания без взаимодействия с пользователем, могут быть устойчивы к другим изменениям.

Если вас интересуют практические примеры, закажите мою JAREST бумагу . Последний раздел о HATEOAS. Вы увидите, что с JAREST даже очень интерактивные и визуально привлекательные клиенты могут быть достаточно устойчивыми к изменениям на стороне сервера, но не на 100%.

Answer 6

Другой пример базового клиента обнаружения во время выполнения: ознакомьтесь с демонстрацией клиента HAL Talk Hypermedia API .

на основе языка приложений гипертекста (XML +Схема JSON для связывания): http://stateless.co/hal_specification.html

Answer 7

Я думаю, что важным моментом в HATEOAS является не то, что это какая-то святая часть клиента Grail, а то, что он изолирует клиента от изменений URI - предполагается, что вы используете известные (или разработчик обнаружил пользовательские) Link Relations, которые позволят система, которая знает, какая ссылка для объекта является редактируемой формой. Важным моментом является использование типа emdia, который поддерживает гипермедиа (например, HTML, XHTML и т. Д.).

Answer 8

Вы пишете:

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

Если этот шаблон ссылки указан в предыдущем запросе, внеполосная информация отсутствует. Например, форма поиска HTML использует шаблон ссылок (/search?q=%@) для генерации URL (/search?q=hateoas), но клиент (веб-браузер) не знает ничего, кроме как использовать формы HTML и GET.