ハイパーメディアクライアント

カーソン・グロス

2023年1月28日

しばしば、オンラインディスカッションでRESTとHATEOASについて、我慢できないほど杓子定規になっているとき、私たちは次のようなことを言います。

JSONはハイパーメディアコントロールを持たないため、ハイパーメディアではありません。

このJSONを見てください。

{
 "account": {
   "account_number": 12345,
   "balance": {
     "currency": "usd",
     "value": 50.00
   },
   "status": "open"
 }
}

ほら？ハイパーメディアコントロールがありません。

そのため、このJSONはハイパーメディアではなく、したがって、このJSONを返すAPIはRESTfulではありません。

これに対して、時折、賢明で経験豊富なWeb開発者が次のように答えます。

わかりました、REST信者の皆さん、このJSONはどうですか？

{
  "account": {
    "account_number": 12345,
    "balance": {
      "currency": "usd",
      "value": 50.00
    },
    "status": "open",
    "links": {
      "deposits": "/accounts/12345/deposits",
      "withdrawals": "/accounts/12345/withdrawals",
      "transfers": "/accounts/12345/transfers",
      "close-requests": "/accounts/12345/close-requests"
    }
  }
}

これで、このレスポンスにハイパーメディアコントロール（普通の人はリンクと呼びます）があるので、このJSONはハイパーメディアです。

つまり、このJSON APIはRESTfulになりました。納得しましたか？

😑

少なくとも表面上は、私たちのオンライン上の敵対者はある程度の主張を持っていることを認めなければなりません。これらはハイパーメディアコントロールのように見え、実際、JSONレスポンスにあります。では、このJSONレスポンスをRESTfulと呼ぶことはできないでしょうか？

生まれつき頑固なので、私たちは良い揚げ足取りなしに、すぐにその点を譲歩するつもりはありません。

まず、これらのリンクには、それらにアクセスするために使用するHTTPメソッドに関する情報がありません。
次に、これらのリンクは、例えば、アンカータグやフォームタグがHTMLと一緒になっているように、JSONのネイティブな部分ではありません。
第三に、各エンドポイントでのハイパーメディアインタラクションに関する情報が欠落しています（例えば、リクエストと一緒にどのようなデータを送信する必要があるかなど）。

などなど、インターネット上でRESTに関する技術的な炎上を特別に楽しいものにする、杓子定規な揚げ足取りです。

しかし、ここにはもっと深い揚げ足取りがあり、それはJSON API自体ではなく、ネットワークの反対側、つまりJSONを受信するクライアントに関するものです。

#ハイパーメディアクライアントとプレゼンテーション情報

RESTfulでないJSON APIに対するこの修正案のより深い問題は、このJSONレスポンスがハイパーメディアシステムに適切に参加するためには、JSONを消費するクライアントも、RESTfulアーキテクチャスタイルがシステム全体に課す制約を満たす必要があるということです。

特に、クライアントは統一インターフェースを満たす必要があります。このインターフェースでは、クライアントコードは、指定されたハイパーメディアをユーザーに表示する機能を超えて、レスポンスの「形状」や詳細については何も知りません。適切に機能するRESTfulシステムでは、クライアントは、特定のハイパーメディア表現が表現するドメインに関する「帯域外」の知識を持つことは許可されていません。

ハイパーメディアとしてのJSONの提案をもう一度見てみましょう。

{
  "account": {
    "account_number": 12345,
    "balance": {
      "currency": "usd",
      "value": 50.00
    },
    "status": "open",
    "links": {
      "deposits": "/accounts/12345/deposits",
      "withdrawals": "/accounts/12345/withdrawals",
      "transfers": "/accounts/12345/transfers",
      "close-requests": "/accounts/12345/close-requests"
    }
  }
}

このAPIのクライアントは、汎用アルゴリズムを使用して、このJSONを、例えば、いくつかのHTMLに変換できます。これは、例えば、JSONオブジェクトのすべてのプロパティを反復処理するクライアントサイドのテンプレート言語を介して行うことができます。

しかし、問題があります。JSONレスポンスには、多くのプレゼンテーション情報がないことに注意してください。これは、いくつかの追加のURLを持つ、問題のアカウントのかなり生のデータ表現です.

RESTの統一インターフェース制約を満たしたいクライアントは、このデータをユーザーにどのように提示するかについての情報があまりありません。したがって、クライアントは、このアカウントをエンドユーザーに表示するために、非常に基本的なアプローチを採用する必要があります。

おそらく、最終的には、名前と値のペアのセットと、アクション用の汎用ボタンまたはリンクのセットになるでしょう？

JSONレスポンスの形式について不可知論的なままで、それ以上のことはできません。

#JSON APIをさらに進化させる

JSON APIをより精巧にし、情報をどのようにレイアウトするかについてのより多くの情報、例えば、いくつかのフィールドを強調したり、隠したりする必要があることを示す情報などを含めることで、これを修正できます.

しかし、それは物語の一部に過ぎません。

また、JSON APIのこれらの新しい要素を正しく解釈するために、クライアント側を更新する必要があります. したがって、私たちはもはやAPI設計者だけではありません。ハイパーメディアクライアント作成ビジネスにも参入しています。あるいは、より可能性が高いのは、私たちのAPIクライアントにもハイパーメディアクライアントビジネスに参入するように求めていることです.

マイク・アムンゼンは、適切な汎用ハイパーメディアクライアントを構築する方法について優れた本を書いています. しかし、その本でわかることは、優れたハイパーメディアクライアントを作成することは些細なことではなく、さらに、JSON APIがレスポンスにますます精巧なハイパーメディアコントロールとプレゼンテーション情報を持っていたとしても、ほとんどのエンジニアがJSON APIを消費するために構築するものでは決してないということです.

#「非効率的な」表現

JSONレスポンスに المزيدの情報を追加することを検討し始めると、ロイ・フィールディングの論文からの引用が頭に浮かびます.

しかし、トレードオフは、統一インターフェースは効率を低下させるということです。情報はアプリケーションのニーズに固有の形式ではなく、標準化された形式で転送されるためです.

- ロイ・フィールディング、https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5

HTMLに対する批判は、「プレゼンテーション」情報と「セマンティック」情報を混在させていることです。これは、多くの場合、典型的なJSON APIレスポンスの簡潔さと不利に比較されます.

しかし、まさにそのプレゼンテーション情報と、Webブラウザ（つまりハイパーメディアクライアント）がそれを人間が対話できるUIに変換する機能が、HTMLをWebというより大きなハイパーメディアシステムのコンポーネントとしてうまく機能させていることがわかります.

そして、それはまさに、適切なハイパーメディアクライアントをサポートするために、独自のJSON APIに追加しているものです.

#ハイパーメディアクライアントの構築

したがって、JSON APIレスポンスでハイパーメディアコントロールを提供するだけでは不十分であることがわかります。それはRESTストーリーの一部ですが、ストーリー全体ではありません。そして、私は理解するようになりましたが、それはストーリーの難しい部分ではありません。実際、ハイパーメディアクライアントを作成することが難しい部分であり、優れたハイパーメディアクライアントを作成することが本当に難しい部分です.

さて、私たちは皆、Webブラウザがそこにあることに慣れていますが、通常の毎日のWebリクエストでHTMLをエンドユーザーに解析してレンダリングするためだけに使われているすべてのテクノロジーについて少し考えてみてください。それは非常に複雑です.

そのため、Webベースのハイパーメディア駆動アプリケーションを構築したい場合は、標準のWebベースのハイパーメディアクライアントであるブラウザを使用することをお勧めします.

それはすでに非常に強力で、十分にテストされたハイパーメディアクライアントです。そして、少し助けがあれば、さらに優れたハイパーメディアクライアントになることができます.

一般に、RESTのすべての制約を満たす優れたハイパーメディアクライアントを構築することは難しいため、独自の新しいクライアントを構築するのではなく、既存のクライアントを使用（および拡張）することに傾倒する必要があります.

#Hyperview

そうは言っても、新しいハイパーメディアクライアントを構築することが適切な場合があります。たとえば、Hyperviewのようなテクノロジーがそれほど印象的で特別なものになっているのはそのためです。Hyperviewは、新しいモバイルフレンドリーなハイパーメディアHXMLの仕様を提供するだけではありません.

また、開発者にHXMLをレンダリングする方法を理解するハイパーメディアクライアントも提供します.

そのハイパーメディアクライアントがなければ、Hyperviewは、上記のJSONのように、理論上のハイパーメディアに過ぎず、説得力のある、実用的で完全なRESTfulハイパーメディアソリューションにはなりません.

ハイパーメディアクライアントのないハイパーメディアは、自転車のない魚のようなものです. ただし、魚は自転車に乗ることだけが本当に得意です.

#結論

適切なRESTfulハイパーメディアシステムにとってクライアントがどれほど重要であるかを理解するには、長い時間がかかりました。これは理解できます。RESTに関する初期の議論のほとんどはAPI設計に関するものであり、クライアントはあまり話題にならなかったためです.

私が今見ているのは、これらの議論の多くが本末転倒だったということです。RESTfulハイパーメディアAPIが役立つ唯一の方法は、適切なハイパーメディアクライアントによって消費される場合です。そうでなければ、あなたのハイパーメディアコントロールは、結局のところ、物事を成し遂げたいだけのドメイン固有のシッククライアントに無駄になります.

さらに、ハイパーメディアAPIは、全体を本当に使いやすくするために、かなりの量のプレゼンテーション層情報を伝える必要があるでしょう。リチャード成熟度モデルの「レベル3」、ハイパーメディアコントロールは、「RESTの栄光」に到達するには不十分であることがわかりました.

実際には、ハイパーメディアAPIを実際に機能させるために、多くの実用的なプレゼンテーションレベルのテクノロジーを追加する必要があり、さらに、それを消費するために適切に構築されたハイパーメディアクライアントが必要になります.

HATEOASは人間のためにあるを書いたとき、私はこれについて漠然とした感覚を持っていましたが、当時、クライアント/ Webブラウザがどれほど特別であるかを理解していませんでした.

RESTはAPIだけではありません。ロイ・フィールディングが彼の論文で明確にしているように、それはシステムアーキテクチャです.

マイクのような少数の人々を除いて、私たちはRESTストーリーのより大きな（実際にははるかに大きな）部分を largely 無視してきました.

Creating A Hypermedia Client Is Hard Joke

</>