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

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

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

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

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

Ответ 1

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

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

Ответ 2

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

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

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

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

Ответ 3

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

В условиях неспециалиста HATEOAS означает ссылку ниже. Этот подход отделяет вашего клиента от определенного URL-адреса и дает вам гибкость в изменении вашего API, не нарушая никого.

Ответ 4

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

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

Ответ 5

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

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

Это конец HATEOAS и, таким образом, конец REST? Да и нет.

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

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

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

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

Ответ 6

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

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

Ответ 7

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

Ответ 8

Вы пишете:

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

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