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

75

Для запуска 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?

  • 2
    Просто немного в стороне от вашей ссылки ОПЦИИ. Вы можете использовать заголовок «Разрешить» для передачи разрешенных операций с ресурсами вне запроса OPTIONS. Рой Филдинг заходит так далеко, что рассматривает заголовок как форму гипертекста - см. Здесь .
  • 0
    В этом вопросе gr8, ключевые вопросы приведены в списке применимых методов, должен ли клиент формировать URL-адреса для обычной операции CRUD или он будет называться «внеполосным»? Скажем, если мы также предоставим ссылки для операций CRUD, как вы создаете "формы" в json? Может быть, если вы используете специфические для приложения типы мультимедиа, вам не нужно делать «формы», но wat является стандартным способом обнаружения типов мультимедиа (то есть схемы json), будет ли процесс обнаружения схемы рассматриваться как не «вне группа "для клиентов"
Показать ещё 1 комментарий
Теги:
rest
hateoas
discovery

8 ответов

33
Лучший ответ

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

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

Поделиться
  • 2
    где-нибудь "клиентский" код src? я не вижу там никакого кода клиента, он просто использует свой клиент в примерах Java
  • 1
    @ Denny1989 Я думаю, что это исходный код: github.com/cimlabs/hypermedia-client-java
Показать ещё 1 комментарий
19

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

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

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

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

Поделиться
  • 0
    Есть ли какой-либо стандарт для реализации такой службы обнаружения для наших собственных API?
11

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

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

Поделиться
  • 0
    Спасибо, что напомнили мне о HATEOAS. Это ключевое слово, которое мне не хватало, чтобы понять, что делать с клиентскими интерфейсами. (Чувак, мне действительно не нравится эта аббревиатура!) Я уже встречал HATEOAS раньше, и, думаю, я усвоил, что это значит, но я забыл использовать имя в своих поисках. Сейчас я вижу много ресурсов, которые дают мне лучшую картину, и некоторые надеются, что это все-таки недостижимо.
  • 0
    образцы IOS? что ты выбрал ? в какой-то момент вам нужно знать, что вы ищете! так что вам нужно знать API, поэтому вам нужно жестко закодировать некоторые вещи!
Показать ещё 2 комментария
5

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

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

Поделиться
3

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

Поделиться
2

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

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

Поделиться
1

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

Поделиться
0

Вы пишете:

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

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

Поделиться
  • 0
    на самом деле нет внеполосной информации - клиент отвечает за расширение шаблонов uri с использованием предоставленных данных ресурса / экземпляра (и должен знать, как это сделать) - json-schema.org/latest/json-schema- hypermedia.html # anchor18

Ещё вопросы

Сообщество Overcoder
Наверх
Меню