Управление версиями REST API при использовании Atom для коллекций ресурсов - PullRequest
3 голосов
/ 16 ноября 2011

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

Я разрабатываю пользовательский API-интерфейс REST для нашего приложения и решил, что я хотел бы создать версию с использованием типов носителей, например, Приложение / vnd.mycompany.resource.v2 + XML. Я понимаю плюсы и минусы этой модели, и кажется, что она наиболее гибкая.

Следовательно, мой GET будет выглядеть следующим образом:

=== REQUEST ===>
GET /workspaces/123/contacts?firstName=Neil&accessID=789264&timestamp=1317611 HTTP/1.1
Accept: application/vnd.mycompany.contact-v2+xml

<== RESPONSE ===
HTTP/1.1 200 OK
Content-Type: application/vnd.mycompany.contact-v2+xml
<contact>
    <name>Neil Armstrong</name>
    <mobile>+61456838435</mobile>
    <email>neil.armstrong@space.com</email>
</contact>

Проблема в том, что я хотел бы использовать каналы и записи Atom для представления своих коллекций ресурсов. Таким образом, я могу использовать поиск и нумерацию страниц Atom без заражения моих ресурсов или структуры API.

Если я использую Atom для своих запросов, моя структура запросов теперь выглядит следующим образом:

=== REQUEST ===>
GET /workspaces/123/contacts HTTP/1.1
Accept: application/atom+xml; type=feed;

<== RESPONSE ===
HTTP/1.1 200 OK
Content-Type: application/atom+xml; type=feed;
<feed xmlns="http://www.w3.org/2005/Atom">
   <title>Contacts Feed</title>
   <link rel="self" href="https://api.mycompany.com/workspaces/contacts"/>
   <updated>2011-11-13T18:30:02Z</updated>
   ...
   <entry>
      <title>Neil Armstrong</title>
      ...
      <content type="application/vnd.mycompany.contact-v2+xml">
          <contact>
              <name>Neil Armstrong</name>
              <mobile>+61456838435</mobile>
              <email>neil.armstrong@space.com</email>
          </contact>
      </content>
   </entry>
</feed>

Используя Atom для представления своих коллекций ресурсов, я теряю возможность создавать версии с использованием типов носителей. Поскольку тип носителя теперь скрыт в содержимом записи Atom.

      <content type="application/vnd.mycompany.contact-v2+xml">

Какова наилучшая практика для определения версии медиа-типа моего ресурса, при этом используя возможности Atom для управления сбором ресурсов?

Я думаю, что могу передать его через заголовок ACCEPT, например

Accept: application/atom+xml; type=feed; version=1.0

Но тогда это сбивает с толку, поскольку вы запрашиваете версию 1.0 фида Atom, а не сам ресурс ...

Любая помощь будет очень признательна !!

1 Ответ

3 голосов
/ 16 ноября 2011

Проблема в том, что ИМХО вы неправильно используете типы мультимедиа.

Типы мультимедиа дают вам информацию о СТРУКТУРЕ фактической полезной нагрузки, но не СЕМАНТИКЕ полезной нагрузки.«Я знаю, что это страница XHTML, но я не знаю, является ли это постом в блоге или элементом на Amazon».Будучи страницей XHTML, вы знаете, как извлечь компоненты из полезной нагрузки и задать интересные вопросы, но интерпретация полезной нагрузки не является частью типа носителя.

Рассмотрим пример, перефразированный из примера.Роя Филдинга, отправка массива 10 000 бит в виде файла GIF размером 100x100 пикселей.GIF, как «все знают», используется для отправки изображений, но это действительно проще, чем это.Это механизм отправки структурированных двоичных файлов, которые просто случаются с изображениями, которые чаще всего используются.Таким образом, в этом случае его использования для отправки массива 10 000 бит (возможно, представленного в виде изображения с серой шкалой 00 и FF) вы получаете преимущество общего декодера (GIF), встроенных в сжатие GIF и т. Д.

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

Еще один пример - несколько лет назад инженер проводил исследования на радаре.Таким образом, он брал 3 чертежа самолета, которые вы найдете в книгах и тому подобное, и кодировал их с помощью планшета в чертежах AutoCAD.Формат DWG был хорошо документирован, и у него был код для их чтения.Ему нужны были координаты и измерения конкретного самолета.

Итак, в конце концов у него была куча «бессмысленных» файлов AutoCAD, в которых не было ничего, кроме ряда строк, которые «не имели смысла».Но на самом деле они были переполнены хорошей информацией для его домена.Файл DWG был медиа-типом, но это были не «чертежи САПР».(Можете ли вы сказать «самопроизвольное повторное использование»?)

Это нормально для версии чего-либо через медиа-тип, но это актуально, только если медиа-тип фактически меняется.Как вы заметили, ATOM не меняется или, по крайней мере, не меняется под вашим контролем, и вы можете отказаться от поддержки новой версии, если / когда она изменится.Но ATOM не меняется, потому что то, как он представляет свою информацию, как эта информация кодируется, не меняется.Информация вполне может измениться, фактически она меняется все время.Каждый канал ATOM отличается своей информацией.У MOST схожая семантика (каналы блога), но у многих ее нет (например, возможно, ваш сценарий).

Но то, как вы будете анализировать и получать информацию из канала ATOM, не изменится.И это то, что представляет тип медиа.Кодировка информации, а не сама информация.

Итак, если вы хотите обнаружить управление версиями, то проверьте в своей полезной нагрузке.Осмотрите это.Вы ЗНАЕТЕ, что для V1 ваших данных, где, например, номер счета-фактуры (возможно, это в invoice / inv_no в XPATH).Если счета нет, то что вы делаете?Вы а) ищете другое известное место (например, V2), или, б) вы выдаваете ошибку («Что бы это ни было, это не счет!»).Вам придется делать это независимо от того, что, потому что вы можете получить что-нибудь, независимо от того, что говорит версия, тип носителя или что-нибудь еще.

Вы можете сделать свои полезные данные вперед совместимыми сбудьте устойчивы к критическим изменениям, тогда версия - это использование всей информации, которую вы видите.Если вы получаете A и B, то, хотя вы также хотите иметь C и D, клиенты могут обойтись более ограниченной информацией.Если клиенты увидят C и D, они будут знать, что игнорируют A и B, поскольку эти данные устарели.То же самое с сервером.Если что-то отправляет A и B, подразумевается, что это более старая модель обработки, чем если бы они отправляли по C и D.

Вы можете создавать версии с помощью имен rel "order" vs "order_2", старые клиенты знают толькоиспользуйте "заказ", новые клиенты знают, что нужно использовать "заказ_2" и перейдите по этой ссылке.

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

Существует множество способов управления версиями, но носительТип действительно не должен быть механизмом.Вот почему это действительно не «проблема» с ATOM.Итак, это вопрос перспективы.

У меня есть еще одно обсуждение заголовка Accept здесь: REST API, имеющий тот же объект, но легкий

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

В конце концов, ваш клиент и / или сервердостаточно гибки для обработки версионных данных или нет.Они будут (в основном, это, в конце концов, компьютеры. Детерминист, моя дорогая ...) делать то, что им говорят.Простое правило «игнорировать вещи, которые вы не знаете» может значительно продвинуть вас с точки зрения управления версиями, даже не заменяя v1 на v2, независимо от вашей кодировки.Точно так же «работа с тем, что у вас есть» - хорошее правило для гибкого, терпимого сервера.Если у вас возникли проблемы в любом случае, для этого нужны ошибки, журналы, операторы и 24-часовые пейджеры, которые вам все равно нужны.

...