HATEOAS Дизайн клиента - PullRequest
       20

HATEOAS Дизайн клиента

8 голосов
/ 24 февраля 2012

Я прочитал много дискуссий здесь о SO, посмотрел презентацию Джона Мура (которая многое объяснила, кстати) и прочитал пост Роя Филдинга в блоге на HATEOAS, но я все еще чувствую себя немного мрачно когда дело доходит до дизайна клиента.

Вопрос по API

Сейчас я просто возвращаю xhtml с формами / якорями и списками определений для представления ресурсов. Следующий фрагмент подробно описывает, как я выкладываю формы / якоря / списки.

# anchors
<li class='docs_url/#resourcename'>
  <a rel='self' href='resource location'></a>
</li>

# forms
<form action='action_url' method='whatever_method' class='???'></form>

# lists
<dl class='docs_url/#resourcename'>
    <dt>property</dt>
    <dd>value</dd>
</dl>

Мой вопрос в основном о формах. В выступлении Джона он документирует типы форм, такие как (add_location_form) и т. Д., И необходимые для них входные данные. У меня не так много ресурсов, но я думал об абстрактных типах форм (добавить, удалить, обновить и т. Д.) И просто отметить в документации, что для (добавления, обновления) необходимо отправить действительное представление целевого ресурса и с delete, что вы должны отправить идентификатор.

Вопрос 1: С понятием HATEOAS, разве мы не должны просто заставить клиента «обнаружить» форму (классифицируя его как добавление, удаление, обновление и т. Д.) И просто отправить обратно все данные, которые мы им дали? Мой настоящий вопрос здесь (не предназначенный для обсуждения) заключается в том, соответствует ли это хорошей практике?

Клиентский вопрос

Вслед за HATEOAS, когда наши действия над ресурсами могут быть обнаружены, как это влияет на код клиента (потребителей API) и их пользовательский интерфейс. Замечательно, что, следуя этим принципам, пользовательский интерфейс должен отображать только доступные действия, но как это реализовано?

Мой текущий подход заключается в синтаксическом анализе ответа в формате xml и использовании xpath для поиска действий, известных на момент разработки клиента (документированные классы форм, например, добавление, удаление, обновление), и отображения элементов управления пользовательского интерфейса, если они доступны. .

Вопрос 2: Я ошибаюсь в своем способе обнаружения? Или это слишком много волшебства для клиента (знание классов форм)? Разве это не предполагает, что клиент знает, какие действия доступны для каждого ресурса (что может быть хорошо, потому что это своего рода причина для создания клиента, верно?) И должно ли документироваться сопоставление действий (классов форм) с ресурсами или просто задокументируйте классы форм и разрешите клиенту (и разработчику клиента) исследовать и обнаруживать их?

Я знаю, что я повсюду с этим, но любое понимание очень ценится. Я отмечу отвеченный ответ, который хорошо отвечает на любой из этих двух вопросов. Спасибо!

1 Ответ

6 голосов
/ 24 февраля 2012

Нет, вы в значительной степени на месте.

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

До сих пор клиенты машин обычно плохо себя чувствуют в «интерпретации».Таким образом, вместо этого разработчики должны принимать решения заранее и направлять машинный клиент в мучительных деталях.

В идеале, «умный» клиент HATEOS должен иметь определенные факты и знать контекст, чтобы он мог лучше отобразитьэти факты в соответствии с требованиями службы.

Потому что это то, что мы делаем, верно?Мы видим форму "О, они хотят имя, адрес, номер кредитной карты".Мы знаем не только, что означают «имя», «адрес» и «номер кредитной карты», мы также можем интуитивно понять, что они означают «МОЕ имя», либо имя человека на кредитной карте, либо имя отправляемого лица.к.

Машины довольно легко выходят из строя и в части "интуитивно".Поэтому, как разработчик, вы получаете код в логике того, что, по вашему мнению, может быть необходимо для определения правильных фактов и того, как они размещены.

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

Вы можете видеть, что тривиальный и явно хрупкий способсделать это просто сопоставить имена параметров с внутренними данными.Когда имя параметра равно «name», вы можете жестко запрограммировать его в нечто вроде: firstName + "" + lastName.Или вы можете рассмотреть фактическое значение rel, чтобы «знать», что они говорят о доставке, и использовать: shipTo.firstName + "" + shipTo.lastName.

Со временем, в идеале, вы могли бы создать коллекцию отображенийи таким образом, что если вдруг полезная нагрузка ввела новое поле, и это оказалось полем, о котором вы уже знаете, вы можете заполнить его также «автоматически» без изменений для клиента.

Но простоПравда в том, что хотя это можно сделать, это в значительной степени не сделано.Семантика обычно слишком расплывчата, вам все равно придется каждый раз кодировать новую «интуицию» для каждой новой полезной нагрузки, так что вы также можете напрямую кодировать полезную нагрузку и покончить с этим.

Ключевым моментом, особенно в HATEOS, является то, что вы не «навязываете» свои данные на сервер.Сервер говорит вам, что он хочет, особенно если они дают вам формы.

Таким образом, мыслительный процесс - это не «О, если я хочу счет на доставку, я вижу, что прямо сейчас они хотят имя, адрес и номер заказа, и они хотят, чтобы его URL был закодирован, и они хотят, чтобы он был отправленна http://example.com/shipping_invoice., поэтому я всегда буду отправлять: name + "&" + address + "&" + orderNumber каждый раз на http://example.com/shipping_invoice. Easy! ".

Скорее то, что вы хотите сделать, это «Я вижу, что они хотят имя, адрес и номер заказа. Поэтому я буду делать для каждого запроса, я буду читать их форму. Я проверю, какие поля онихочу каждый раз. Если они хотят имя, я дам им имя. Если они хотят адрес, я дам им адрес. Если они хотят номер заказа, я дам им номер заказа. И если у них есть какие-либо предварительно заполненные поля (илидаже «скрытые» поля), я тоже отправлю их обратно и отправлю в том коде, который они запрашивали, при условии, что я его поддерживаю, на URL-адрес, полученный из поля действия тега FORM. ".

Вы можете видеть, что в первом случае вы ПРИНИМАЕТЕ, что им каждый раз нужна эта полезная нагрузка.Так же, как если бы вы были жестко кодировать URL-адреса.Тогда как со вторым, может быть, они решили, что имя и адрес избыточны, поэтому они больше не просят об этом.Возможно, они добавили несколько хороших настроек по умолчанию для новых функций, которые вы, возможно, еще не поддерживает.Может быть, они изменили кодировку на несколько частей?Или изменил URL конечной точки.Кто знает.

Вы можете отправлять то, что знаете, только когда кодируете клиент, верно?Если они меняют вещи, то вы можете делать только то, что умеете.Если они добавляют поля, мы надеемся, что они добавляют поля, которые не являются обязательными.Но если они нарушают интерфейс, эй, они нарушают интерфейс, и вы получаете сообщение об ошибке.Вы мало что можете сделать там.

Но чем больше вы используете часть HATEOS, тем больше она становится доступной для вас, так что вы можете быть более гибкими: заполнять формы, правильно перенаправлять, обращать внимание накодирование и типы мультимедиа, тем более гибким становится ваш клиент.

В конце концов, большинство людей просто не делают этого на своих клиентах.Они жестко зашифровывают их, потому что это просто, и они предполагают, что серверная часть не изменяется достаточно быстро, чтобы иметь значение, или что любое время простоя, если такое изменение действительно имеет место, является приемлемым, пока они не исправят клиента.Более типично, особенно с внутренними системами, вы просто получите электронное письмо от разработчиков: «Они меняли XYZ API, и он начнет действовать 1 марта. Пожалуйста, обновите ваших клиентов и координируйте свою работу с командой релиза во время интеграционного тестирования.

Это просто реальность.Это не означает, что вы не должны этого делать или что вы не должны делать свои серверы более дружественными для более умных клиентов.Помните, плохой клиент, который предполагает, что все не делает недействительной хорошую систему на основе REST.Эти системы прекрасно работают с ужасными клиентами.wget ftw, а?

...