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

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

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

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

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

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

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

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

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

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

Очаровательно. То, что вы описываете, по сути является принципом HATEOAS. Вы спросите, что такое HATEOAS? Прочтите это: http://en.wikipedia.org/wiki/HATEOAS

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

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

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

Одно из требований, которое должно быть выполнено, прежде чем вы сможете вызвать 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%.

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

Ты пишешь:

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

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