RESTful API runtime discoverability / дизайн клиента HATEOAS
для запуска SaaS, в котором я участвую, я создаю как RESTful web API, так и несколько клиентских приложений на разных платформах, которые его потребляют. Я думаю, что у меня есть API, но теперь я обращаюсь к клиентам. Поскольку я читал об отдыхе, я вижу, что ключевой частью отдыха является открытие, но, похоже, существует много споров между двумя разными интерпретациями того, что на самом деле означает открытие:
разработчику открытие!--8-->: разработчик жестко кодирует большое количество деталей API в клиент, таких как URI ресурса, параметры запроса, поддерживаемые методы HTTP и другие детали, которые они обнаружили при просмотре документов и экспериментируя с ответами API. Этот тип обнаружения IMHO требует прохладной связи и вопроса управления версиями API и приводит к жесткой связи клиентского кода с API. Не намного лучше, чем при использовании хорошо документированной коллекции RPC кажется.
во время выполнения обнаружения - само клиентское приложение способно выяснить все, что ему нужно, с небольшой или никакой внеполосной информацией (предположительно, только знание типов носителей, с которыми имеет дело API.) Ссылки могут быть горячими. Но чтобы сделать API очень эффективным, кажется, что требуется много шаблонов ссылок для параметров запроса,что заставляет внеполосную информацию возвращаться. Возможно, есть и другие трудности, о которых я еще не думал, так как не думал. дошли до этого момента в развитии. Но мне нравится идея свободной связи.
Runtime discovery кажется Святым Граалем покоя, но я вижу очень мало дискуссий о том, как реализовать такого клиента. Почти все остальные источники, которые я нашел, похоже, предполагают обнаружение разработчика. Кто-нибудь знает о некоторых ресурсах runtime discovery? Передовая практика? Примеры или библиотеки с реальным кодом? Я работаю в PHP (Zend Framework) для одного клиента. Цель-C (iOS) для другого.
является ли обнаружение среды выполнения реалистичной целью, учитывая нынешний набор инструментов и знаний в сообществе разработчиков? Я могу написать своему клиенту, чтобы обработать все URI непрозрачным образом, но как это сделать наиболее эффективно, это вопрос, особенно по соединениям с низкой пропускной способностью. В любом случае, URI-это только часть уравнения. Как насчет шаблонов ссылок в контексте выполнения? Как насчет обмена информацией о том, какие методы поддерживаются, помимо создания множества опций просьбы?
8 ответов
в этом видео Джон Мур создает общий клиент, используя время выполнения HATEOAS auto discovery. Это довольно впечатляет и стоит посмотреть:
http://oredev.org/oredev2010/2010/sessions/hypermedia-apis.html
Это определенно Крепкий орешек. В Google мы внедрили наш сервис обнаружения, на котором построены все наши новые API. Версия TL; DR-это мы генерируем спецификацию, подобную схеме JSON, которую наши клиенты могут анализировать-многие из них динамически.
эти результаты означают более легкие обновления SDK для разработчика и легкое/лучшее обслуживание для нас.
отнюдь не идеальное решение, но многие из наших разработчиков, похоже, нравится.
посмотреть ссылке для подробнее (и убедитесь, что смотрите видео.)
увлекательный. То, что вы описываете в основном принцип HATEOAS. Что такое HATEOAS вы спрашиваете? Прочтите это:http://en.wikipedia.org/wiki/HATEOAS
в терминах непрофессионала, HATEOAS означает ссылку. Этот подход отделяет ваш клиент от конкретных URL-адресов и дает вам гибкость для изменения вашего API, не нарушая никого.
вы сделали свою домашнюю работу, и вы попали в самое сердце: runtime discovery-Святой Грааль. Не гоняйся за ним.
UDDI рассказывает о мучительной истории обнаружения времени выполнения:http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration
одно из требований, которое должно быть выполнено, прежде чем вы сможете вызвать API "RESTful", заключается в том, что должно быть возможно написать общее клиентское приложение поверх этого API. С помощью универсального клиента пользователь должен иметь доступ ко всем функциям API. Универсальный клиент-это клиентское приложение, которое не предполагает, что любой ресурс имеет определенную структуру за структурой, которая определяется типом СМИ. Например, веб-браузер-это общий клиент, который знает, как интерпретируйте HTML, включая HTML-формы и т. д.
теперь предположим, что у нас есть API HTTP/JSON для веб-магазина, и мы хотим создать клиент HTML/CSS/JavaScript, который дает нашим клиентам отличный пользовательский интерфейс. Было бы реалистичным вариантом позволить этому клиенту быть generic клиентское приложение? Нет. Мы хотим предоставить определенный внешний вид для каждого конкретного элемента данных и каждого конкретного состояния приложения. Мы не хотим включать все знания об этих презентация-специфика в API, наоборот, клиент должен определить внешний вид и API должен нести только данные. Это означает, что клиент жестко связывает определенные элементы ресурсов с определенными макетами и взаимодействиями пользователей.
Это конец HATEOAS и, таким образом, к концу отдыха? да и нет.
да, потому что если мы знание жесткого кода об API в клиент, мы теряем преимущество HATEOAS: серверные изменения могут повредить клиенту.
нет, по двум причинам:
- быть "RESTful" является свойством API, а не клиента. Пока это возможно,в теории, чтобы создать общий клиент, который предлагает все возможности API, API можно назвать RESTful. Тот факт, что клиенты не подчиняются правилам, не является виной API. Тот факт, что общий клиент будет иметь паршивый пользовательский интерфейс, не является проблемой. Почему? важно знать, что это возможно иметь общий клиент, если мы нет, что общий клиент? Это подводит меня ко второй причине:--26-->
- RESTful API предлагает клиентам возможность выбрать, насколько универсальными они хотят быть, т. е. насколько устойчивыми к изменениям на стороне сервера они хотят быть. Клиенты, которые должны предоставить большой пользовательский опыт, могут быть устойчивы к изменениям URI, к изменениям значений по умолчанию и более. Клиенты пакетного задания без взаимодействия с пользователем могут быть устойчивы к другим видам изменений.
Если вас интересуют практические примеры, протокол JAREST paper. Последний раздел о HATEOAS. Вы увидите, что с JAREST даже очень интерактивные и визуально привлекательные клиенты могут быть довольно устойчивы к изменениям на стороне сервера, хотя и не на 100%.
для другого примера основного клиента обнаружения времени выполнения проверьте HAL Talk Hypermedia API client demo.
на основе языка гипертекстового приложения (схема XML+JSON для связывания):http://stateless.co/hal_specification.html
Я думаю, что важный момент о HATEOAS заключается не в том, что это какая-то клиентская сторона Святого Грааля, а в том, что она изолирует клиента от изменений URI - предполагается, что вы используете известные (или обнаруженные пользовательские) связи, которые позволят системе узнать, какая ссылка для объекта является редактируемой формой. Важным моментом является использование типа emdia, который является гипермедиа (например, HTML, XHTML и т. д.).
вы пишете:
чтобы сделать API очень эффективным, требуется много шаблонов ссылок для параметров запроса, что делает внеполосную информацию ползучей обратно.
Если этот шаблон ссылки указан в предыдущем запросе, то нет никакой внеполосной информации. Например, форма поиска HTML использует шаблон ссылок (/search?q=%@) для создания URL-адреса (/search?q=hateoas), но ничего не известно клиенту (веб-браузеру), кроме того, как использовать HTML-формы и GET.