IT 技書の森

HATEOAS

REST API のレスポンスにリンクを含め、クライアントが次に取れるアクションを動的に発見できるようにする設計原則

API

HATEOAS とは

HATEOAS (Hypermedia As The Engine Of Application State) は、REST アーキテクチャの制約の 1 つで、API のレスポンスに「次に取れるアクション」へのリンクを含める設計原則である。クライアントは URL をハードコードせず、レスポンスに含まれるリンクをたどって操作を進める。

Roy Fielding が 2000 年の博士論文で REST を定義した際、HATEOAS は REST の必須要素として位置づけられた。しかし実際には、HATEOAS を完全に実装している API は少数派だ。Richardson の REST 成熟度モデルではレベル 3 (最高レベル) に位置する。

具体例

// 注文の取得レスポンス (HATEOAS なし)
{
  "orderId": "ORD-123",
  "status": "pending",
  "total": 5000
}

// 注文の取得レスポンス (HATEOAS あり)
{
  "orderId": "ORD-123",
  "status": "pending",
  "total": 5000,
  "_links": {
    "self": { "href": "/orders/ORD-123" },
    "cancel": { "href": "/orders/ORD-123/cancel", "method": "POST" },
    "payment": { "href": "/orders/ORD-123/payment", "method": "POST" }
  }
}

status が shipped に変わると、cancel リンクが消え、track リンクが出現する。クライアントはリンクの有無で「今キャンセルできるか」を判断できる。ビジネスロジックの判断がサーバー側に集約される。

HATEOAS のメリット

クライアントとサーバーの疎結合

クライアントが URL をハードコードしないため、サーバー側で URL 構造を変更してもクライアントの修正が不要になる。/api/v1/orders を /api/v2/orders に変更しても、クライアントはレスポンスのリンクをたどるだけだ。

状態遷移の明示

「この注文は今キャンセルできるか」をクライアントが自前で判断する必要がない。cancel リンクが存在すればキャンセル可能、存在しなければ不可能。UI のボタンの表示/非表示をリンクの有無で制御できる。

API の自己記述性

レスポンスを見るだけで、次に何ができるかが分かる。API ドキュメントを参照しなくても、リンクをたどることで API の全機能を発見できる (理論上は)。

HATEOAS を採用しない理由

実務では HATEOAS を完全に実装しないケースが多い。その理由を理解しておくことが重要だ。

実装コストが高い

すべてのレスポンスにリンクを含めるには、各リソースの状態に応じて動的にリンクを生成するロジックが必要だ。単純な CRUD API に対してはオーバーエンジニアリングになりやすい。

フロントエンドとの相性

SPA (Single Page Application) やモバイルアプリでは、画面遷移のロジックがクライアント側にある。サーバーが返すリンクに従って画面遷移するモデルは、現代のフロントエンド開発と噛み合わない場面がある。

標準フォーマットの乱立

HATEOAS のリンク形式には HAL、JSON:API、Siren、JSON-LD など複数の標準が存在し、統一されていない。どれを採用するかの判断コストが発生する。

実務での落としどころ

完全な HATEOAS を実装しなくても、部分的に取り入れることで恩恵を得られる。

  • ページネーション: next、prev、first、last のリンクをレスポンスに含める。これは広く普及しており、GitHub API や AWS API でも採用されている
  • 関連リソース: 注文レスポンスに customer や items へのリンクを含め、クライアントが必要に応じて取得できるようにする
  • 状態遷移: 注文のステータスに応じて、可能なアクション (cancel、refund) のリンクを動的に返す

HATEOAS vs 通常の REST

観点 通常の REST HATEOAS
リンク クライアントが URL を構築 サーバーがリンクを提供
結合度 URL 構造に依存 リンクに従うだけ
発見可能性 API ドキュメントが必要 レスポンスから発見
実装コスト 低い 高い
採用率 高い 低い

さらに掘り下げるなら関連書籍が参考になる。

関連用語