ハイパーメディア APIとは、ハイパーメディア、典型的にはHTTP経由のHTMLを返すAPIです。このスタイルのAPIは、ハイパーメディアを返さないデータAPIとは区別されます。後者のスタイルのAPIで今日最もよく知られているのは、遍在するJSON APIです。
これら2つの異なるタイプのAPIは、明らかに異なる設計上のニーズを持つため、作成時に異なる設計制約を使用し、異なる目標を採用する必要があります。
ハイパーメディアAPI
一方、データAPIは
今日、APIは通常、HTTP経由のJSONという観点から考えられています。これらは、ハイパーメディアの概念が組み込まれている場合もありますが（通常はエンドユーザーにほとんどメリットがありません）、ほとんどの場合、ハイパーメディアAPIではなくデータ指向のAPIです。業界がデータAPIをRESTfulモデルに適合させることの問題を認識し始めたため、RESTful APIから離れる動きがありました。
これは良いことです。業界はデータAPIの世界におけるRESTfulの考え方に疑問を呈し、その特定のネットワークアーキテクチャによりよくサービスを提供した古いクライアントサーバーテクノロジーに目を向け始め、RESTはそれが造られたネットワークアーキテクチャ、つまりハイパーメディアAPIに残すべきです。
ハイパーメディアAPIがデータAPIとどのように異なる設計になるかを示すために、最近htmx Discordで提起された次の状況を考えてみましょう。
フォームとテーブルが1つのページに欲しいです。フォームはテーブルに新しい要素を追加し、テーブルは30秒ごとにポーリングして他のユーザーからの更新が表示されるようにします。
このUIをベースURL /contacts という観点から考えてみましょう。
最初に必要なのは、フォームと現在の連絡先のテーブルを取得するためのエンドポイントです。これは/contacts に配置され、次のようになります。
GET /contacts -> render the form & contacts table
次に、連絡先を作成できるようにします。これは、同じURLへのPOSTを介して行われます
GET /contacts -> render the form & contacts table
POST /contacts -> create the new contact, redirect to GET /contacts
HTMLは次のようになります。
<div>
<form action='/contacts' method="post">
<!-- form for adding contacts -->
</form>
<table>
<!-- contacts table -->
</table>
</div>
これまでのところ、標準的なWeb 1.0アプリケーションであり、データAPIとハイパーメディアAPIのニーズはそれほど分岐していませんが、ハイパーメディアAPIは自己記述的であり、ハイパーメディアアプリケーションを壊すことなく変更できることに注意してください（たとえば、連絡先を作成するためのURLを変更する）。
それでは、htmxが必要な部分、つまりテーブルの更新をサーバーに定期的にポーリングする部分に進みましょう。これを行うために、連絡先のテーブルのみをレンダリングする新しいエンドポイント /contacts/table を追加します
GET /contacts -> render the form & contacts table
POST /contacts -> create the new contact, redirect to GET /contacts
GET /contacts/table -> render the contacts table
そして、テーブルにポーリングトリガーを追加します
<div>
<form action='/contacts' method="post">
<!-- form for adding contacts -->
</form>
<table hx-trigger="every 30s" hx-get="/contacts/table" hx-swap="outerHTML">
<!-- contacts table -->
</table>
</div>
ここで、ハイパーメディアAPIとデータAPIが分岐し始めます。この新しいエンドポイントは、データモデルのニーズではなく、ハイパーメディアのニーズによって完全に駆動されます。アプリケーションのハイパーメディアのニーズが変われば、このエンドポイントはなくなってしまう可能性があります。その形式は劇的に変化する可能性があり、システムは自己記述的であるため、それはまったく許容されます。
HTMLを更新してポーリングにhtmxを使用したので、より良いUXエクスペリエンスのためにフォームにもhtmxを使用することができます
<div>
<form action='/contacts' method="post" hx-boost="true">
<!-- form for adding contacts -->
</form>
<table hx-trigger="every 30s" hx-get="/contacts/table" hx-swap="outerHTML">
<!-- contacts table -->
</table>
</div>
必要に応じて、サーバー側の入力検証、動的フォームなどのためのエンドポイントを追加できます。これらのエンドポイントは、データモデルの考慮事項ではなく、ハイパーメディアのニーズによって駆動されます。アプリケーションで何を達成しようとしているかという観点から考えます。
この短いエッセイの要点はこのです。ハイパーメディアシステムでは、ハイパーメディアシステムのメッセージは自己記述的であるため、APIの変更は問題ありません。APIをいじくり回してもアプリケーションは壊れません。人間のユーザーは単に新しいハイパーメディア（HTML）を見て、実行したいアクションを選択します。
コンピューターと比較して、人間は何をすべきかを決定するのが得意であり、変化にはかなり対応できます。
これはデータAPIとは対照的です。データAPIはクライアントコードを壊すことなく変更することはできないため、変更においてはるかに規律を守る必要があります。また、データAPIは、変更なしでより多くのクライアントのニーズを満たすことができるように、より高いレベルの表現力を提供するというプレッシャーにさらされています。
ハイパーメディアAPIを設計する場合は、データAPIとは異なる設計思考を使用する必要があります。変更はそれほど懸念事項ではなく、優れたハイパーメディアエクスペリエンスに必要なエンドポイントを提供することが主な目標となるはずです。