// シス担のミカタ
API設計

HATEOAS はてぉあす

RESTハイパーメディアAPI設計リンク駆動リソースRESTful
HATEOASって何？読み方もわからない…

簡単に言うとこんな感じ！

レストランのメニューみたいなイメージだよ！ APIのレスポンスに「次にできる操作へのリンク」が一緒に入ってくるから、クライアント側が「次は何をすればいいか」を自分で判断できるんだ。地図なしでも道案内してくれるAPIの仕組みってこと！

HATEOASとは

HATEOAS（Hypermedia As The Engine Of Application State）は、RESTアーキテクチャの制約条件のひとつで、APIのレスポンスに「次に実行できる操作へのリンク（ハイパーメディアリンク）」を含めることで、クライアントがサーバーの状態遷移を自律的に辿れるようにする設計原則です。読み方は「ハテオアス」が一般的です。

通常のAPIでは、クライアント（呼び出し側）が「注文するには /orders にPOSTすればいい」という知識を事前に持っていなければなりません。しかしHATEOASでは、レスポンスのJSONやXMLに "links": [{"rel": "create-order", "href": "/orders"}] のような情報が含まれるため、クライアントはAPIドキュメントを暗記しなくてもリンクを辿るだけで操作が完結します。

これは「アプリケーションの状態をハイパーメディアで駆動する」という考え方で、Roy Fielding氏が2000年の博士論文でRESTの成熟度として定義しました。現実には完全なHATEOAS実装は少ないものの、API設計の理想形として広く参照されています。

HATEOASの仕組みと構造

HATEOASの本質は「レスポンスにリンクを埋め込むこと」です。以下のような形でAPIレスポンスが返ってきます。

{
  "orderId": "12345",
  "status": "pending",
  "total": 3800,
  "_links": {
    "self":   { "href": "/orders/12345" },
    "pay":    { "href": "/orders/12345/payment", "method": "POST" },
    "cancel": { "href": "/orders/12345/cancel",  "method": "DELETE" }
  }
}

この例では「注文が pending（保留中）のとき、次に “支払い” か “キャンセル” ができる」という状態遷移がレスポンスに含まれています。

状態ごとに変わるリンク

HATEOASの肝は「状態によってリンクが変わる」点です。

注文ステータス含まれるリンク
pending（保留）pay（支払い）、cancel（キャンセル）
paid（支払済）ship（発送）、refund（返金）
shipped（発送済）track（追跡）、return（返品）
completed（完了）review（レビュー投稿）

クライアントは「今の状態で何ができるか」をリンクの有無で判断するだけでよく、ビジネスロジックをクライアント側に持つ必要がありません。

覚え方：「次の手を教えてくれる親切なAPI」

HATEOAS… 「HATE（嫌い）」とは逆で、「次の操作を教えてくれる大好きなAPI」と覚えると逆説的で記憶に残ります。あるいは「ハテ？どこへ？→リンクが教えてくれる」と語呂合わせで。

歴史と背景

  • 2000年 — Roy Fielding氏がカリフォルニア大学の博士論文「Architectural Styles and the Design of Network-based Software Architectures」でRESTを定義。HATEOASはその中核的制約として位置づけられた
  • 2008年ごろ — REST APIが普及し始めるが、HATEOASを完全実装するAPIはほとんどなく「理想論」として扱われることが多かった
  • 2010年 — Leonard Richardson が「Richardson成熟度モデル」を提唱。Level 3としてHATEOASを位置づけ、実践的な指標が生まれた
  • 2010年代前半 — Spring HATEOAS（Javaフレームワーク）など、HATEOASを実装しやすくするライブラリが登場
  • 2010年代後半 — GraphQLやgRPCの台頭により、RESTの代替が議論されるように。しかしHATEOASの概念はWeb APIの設計原則として依然参照される
  • 現在 — 完全なHATEOAS実装は少ないが、_links や _embedded を含む HAL（Hypertext Application Language） などの形式として部分的に広く使われている

Richardson成熟度モデルとの関係

HATEOASを理解するには「Richardson成熟度モデル（RMM）」が便利です。RESTful APIの完成度を4段階で評価する指標で、HATEOASはその最高レベルに位置します。

Richardson 成熟度モデル（RMM） Level 0 HTTP を単なるトンネルとして使用（例: SOAP、XML-RPC） Level 1 リソースごとに個別のURLを持つ（/users/1, /orders/2 など） Level 2 HTTP メソッド（GET/POST/PUT/DELETE）を適切に使い分ける Level 3（HATEOAS） レスポンスに「次の操作へのリンク」を含める クライアントはリンクを辿るだけでAPI操作が完結する ★ 成熟度 高い

多くの実務APIはLevel 2止まりで、Level 3（HATEOAS）は「理想的だが実装コストが高い」として省略されることが多いのが現実です。

主要なHATEOAS形式の比較

形式特徴リンク記法例
HAL最も普及。_links キーを使う"_links": {"self": {"href": "/orders/1"}}
JSON:APIリソース関係を厳密に定義"links": {"self": "/orders/1"}
Sirenアクション（フォーム）も表現できる"actions": [{"name": "add-item", ...}]
JSON-LD + Hydraセマンティックウェブ対応"@context" を使ったRDFベース

関連する規格・RFC

規格・RFC番号内容
RFC 8288Web Linking — HTTPヘッダおよびリンク要素でのリンク関係定義の標準
RFC 6570URI Template — HATEOASのリンクテンプレート記法に使われるURI変数展開の仕様
RFC 4287Atom Syndication Format — ハイパーメディアリンクの先行実装として参照される

関連用語

  • REST — HATEOASはRESTの最上位制約。セットで理解すべき設計思想
  • RESTful API — RESTの原則に従って設計されたAPI全般
  • HTTP メソッド — GET/POST/PUT/DELETEなどHATEOASのリンクで指定するメソッド
  • JSON — HATEOASのリンク情報を記述するデータ形式
  • OpenAPI — REST APIの仕様を記述する標準フォーマット（HATEOASとは別アプローチ）
  • GraphQL — HATEOASに代わるAPI設計手法として比較されることが多い
  • URI — HATEOASのリンク先を示すリソース識別子
  • HAL — HATEOASを実装するための最も普及したJSON形式（Hypertext Application Language）