【実務・中級編】 HATEOASの概念と実装 – Web APIアーキテクチャ・データ連携実践ガイド

こんにちは、インフラの深淵を覗き続けるシニアネットワークエンジニアの私です。

これまで幾百ものAPIトラブルシューティングや、夜を徹したルーティング・ロードバランシングの設計に関わってきましたが、ネットワークの世界とアプリケーションの世界は、突き詰めると「いかに美しく、かつ疎結合にパケットやメッセージを流すか」という一点において完全に同期しています。

今回は、REST APIの究極の制約でありながら、現場では「ロマン枠」として敬遠されがちな HATEOAS（Hypermedia As The Engine Of Application State） について、その本質を徹底的に紐解いていきましょう。教科書をなぞるだけの退屈な解説ではなく、実務の現場でどう生き、どう実装すべきか、泥臭い知見を交えてお伝えします。

—

1. なぜ「URLのハードコード」はインフラを崩壊させるのか

APIを設計する際、次のようなエンドポイントを作ったことはありませんか？

GET /api/v1/orders/12345

このレスポンスとして、注文の詳細情報（金額、商品名、ステータス）をJSONで返すのは定石です。では、クライアント（フロントエンドや別のマイクロサービス）が「この注文をキャンセルしたい」と思ったとき、どうやってそのアクションを実行するでしょうか？

多くの現場では、クライアント側のコードに次のようなURLをハードコードしています。

DELETE /api/v1/orders/12345/cancel

一見、何の問題もないように見えます。しかし、ここにアーキテクチャの罠があります。
もし将来、インフラ側のリファクタリングやAPIバージョンの刷新によって、キャンセルのエンドポイントが /api/v2/orders/12345/abort に変わったらどうなるでしょうか？ クライアント側のコードをすべて書き直し、再デプロイする地獄の作業が待っています。これは、Webが本来持っている「自己記述性（Self-descriptive）」を完全に殺した、密結合な設計の典型です。

ハイパーメディアという名の「ナビゲーション」

ここで登場するのが HATEOAS です。
Webの最高傑作である「HTML」を思い出してください。私たちがWebブラウザを使うとき、URLを直接推測して入力するわけではありません。ページに表示されている「リンク（<a>タグ）」や「フォーム（<form>タグ）」をクリックすることで、サーバーから提示された次のアクションへと動的に遷移していきます。

HATEOASは、このブラウザの仕組みをそのままREST API（JSONなどの機械可読なメディアタイプ）に持ち込む概念です。APIサーバーは、現在のリソースの状態だけでなく、「今、クライアントが次に実行できる操作（リンク）のリスト」をレスポンスに動的に含めて返却します。

これにより、クライアントはエンドポイントの構造を一切知る必要がなくなります。ただレスポンスに含まれるリンクを辿るだけで、システム全体を航海（Navigation）できるのです。

—

2. 実践：HATEOASを実装したJSONレスポンスの構造

では、実際にどのようなJSONを返すべきか、具体的な例を見てみましょう。
メディアタイプとしては、標準化された application/vnd.api+json や、シンプルな独自構造（HAL: Hypertext Application Languageなど）がよく使われます。ここでは、実務で最も直感的で採用しやすいHALライクな構造を例に取ります。

{
  "data": {
    "order_id": "12345",
    "status": "processing",
    "total_amount": 15800,
    "currency": "JPY"
  },
  "_links": {
    "self": {
      "href": "/api/v2/orders/12345",
      "method": "GET",
      "description": "このリソースの自己参照URL"
    },
    "cancel": {
      "href": "/api/v2/orders/12345/cancel",
      "method": "POST",
      "description": "注文が処理中の場合のみ有効なキャンセルアクション"
    },
    "invoice": {
      "href": "/api/v2/orders/12345/invoice",
      "method": "GET",
      "description": "発行済みの請求書PDFを取得するURL"
    }
  }
}

このレスポンスの肝は _links オブジェクトです。
もし注文のステータスが shipped（出荷済み） に変わっていたら、サーバー側はこの _links から cancel の項目を意図的に除外します。クライアントは、「あ、今はこの注文をキャンセルするリンクが存在しないから、キャンセルボタンを非活性にしよう」と、サーバー側のビジネスロジックに追従して動的にUIや挙動を変化させることができます。

—

3. Python（FastAPI）によるHATEOAS対応APIの実装例

口で言うのは簡単ですが、実務のコードに落とし込むにはどうすればよいか。
ここでは、モダンなPython製フレームワークである FastAPI を使って、動的にリンクを生成するシンプルなAPIサーバーの実装例を示します。

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
from typing import Dict, Any, Optional

app = FastAPI(title="HATEOAS Sample API", version="2.0")

# 模擬的なデータベース
DATABASE = {
    "12345": {
        "order_id": "12345",
        "status": "processing",
        "total_amount": 15800
    },
    "67890": {
        "order_id": "67890",
        "status": "shipped",
        "total_amount": 5400
    }
}

class OrderResponse(BaseModel):
    data: Dict[str, Any]
    links: Dict[str, Dict[str, str]]

@app.get("/api/v2/orders/{order_id}", response_model=OrderResponse)
def get_order(order_id: str):
    order = DATABASE.get(order_id)
    if not order:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, 
            detail="Order not found"
        )
    
    # 基本のリンク（自己参照）
    links = {
        "self": {
            "href": f"/api/v2/orders/{order_id}",
            "method": "GET"
        }
    }
    
    # ステータスに応じて動的にリンク（次のアクション）を追加する
    if order["status"] == "processing":
        links["cancel"] = {
            "href": f"/api/v2/orders/{order_id}/cancel",
            "method": "POST"
        }
    elif order["status"] == "shipped":
        links["tracking"] = {
            "href": f"/api/v2/shipping/{order_id}/status",
            "method": "GET"
        }

    return {
        "data": order,
        "links": links
    }

このコードのポイントは、status の値によってレスポンスに含める links の内容を切り替えている点です。サーバー側でビジネスルールをカプセル化し、クライアント側はその指示に従うだけの「薄いクライアント（Thin Client）」を構築できます。

—

4. クライアント側の実装（Fetch API）とデバッグの極意

サーバーからHATEOAS形式のレスポンスが返ってくるようになったら、クライアント側（JavaScriptなど）の実装も変わります。URL文字列を組み立てるのではなく、レスポンスの _links キーをパースしてリクエストを飛ばす設計にします。

以下は、curl コマンドで挙動を確認したあとに動かすことを想定した、モダンな JavaScript (Fetch API) の実装例です。

// 1. まずは初期リソース（注文情報）を取得する
async function fetchOrder(orderId) {
  try {
    const response = await fetch(`/api/v2/orders/${orderId}`);
    if (!response.ok) throw new Error('リソースの取得に失敗しました');
    
    const body = await response.json();
    console.log('取得したデータ:', body.data);
    
    // 2. レスポンスに含まれるリンクを元に、次のアクションを判定・実行する
    const links = body.links;
    
    if (links.cancel) {
      console.log('キャンセルアクションが許可されています:', links.cancel.href);
      // 必要に応じて動的にキャンセル処理を実行する関数を呼ぶ
      // await executeCancel(links.cancel.href, links.cancel.method);
    } else {
      console.log('現在、この注文に対するキャンセルアクションは利用できません。');
    }
    
  } catch (error) {
    console.error('エラー発生:', error);
  }
}

// 実行例
fetchOrder('12345');

ネットワークエンジニア・インフラ運用者からの実務Tips

HATEOASを実際のエンタープライズ環境やマイクロサービスアーキテクチャに導入する際、インフラレイヤーで必ず直面する課題がいくつかあります。

1. リバースプロキシやAPI GatewayでのURL書き換え問題

  • バックエンドのコンテナ内では http://internal-service/api/v2/... と認識しているURLが、フロントのAPI Gateway（NginxやKongなど）を通過する際に https://api.example.com/api/v2/... に変わるケースがあります。
  • HATEOASのレスポンス内に絶対パス（フルURL）を含める場合、プロキシ側で X-Forwarded-Host や X-Forwarded-Proto を正しく渡し、アプリケーション側でホスト名を動的に組み立てるか、あるいは相対パス（例: /api/v2/orders/...）で統一してクライアント側に解決させる設計にするのが安全です。

2. キャッシュ（HTTP Caching）との相性

  • HATEOASを導入したリソースは、状態（ステータス）の遷移によって _links の内容が動的に変わります。
  • Cache-Control: no-cache や適切な ETag / Last-Modified のヘッダー設計を行わないと、古いリンク情報がCDNやブラウザにキャッシュされ、存在しないエンドポイントにリクエストが飛ぶ原因になります。

—

まとめ

HATEOASは、一見すると「オーバーエンジニアリング（過剰な設計）」に見えがちです。小規模なシステムや、社内の閉じた数個のAPI間でやり取りするだけであれば、URLのハードコードでも運用できてしまうでしょう。

しかし、システムが巨大化し、マイクロサービスが乱立し、クライアントアプリ（iOS/Android/Web）のバージョンが多様化するフェーズに突入した瞬間、ハードコードされたURLの依存関係は開発チームの足枷となります。

「サーバーがクライアントの道案内をする」というWebの原点に立ち返り、しなやかで変更に強いAPIアーキテクチャを築き上げるために、ぜひHATEOASの概念をあなたのシステム設計の引き出しに加えてみてください。パケットの向こう側にあるアプリケーションの挙動が、より美しく、よりロバストになるはずです。

スポンサーリンク

コメント

タイトルとURLをコピーしました