こんにちは！ネットワークとプロトコルの深淵をこよなく愛するエンジニアです。
今日は、Web APIの設計において「RESTの最終形態」とも呼ばれる HATEOAS（ヘイトオス） についてお話しします。「名前が難しそう…」と身構える必要はありません。実はこれ、私たちが普段、郵便や町中の案内板から自然に受け取っている「最高に親切な仕組み」そのものなんです。
一歩ずつ、現実世界と照らし合わせながら紐解いていきましょう！
—
1. HATEOASって、結局なに？
HATEOAS（Hypermedia As The Engine Of Application State）は、一言で言うと「次に何ができるかを、APIが教えてくれる仕組み」のことです。
想像してみてください。あなたは今、見知らぬ街の大きな駅に降り立ちました。目的の場所へ行くために、駅の出口には「ここを右に行けばバス停、直進すればタクシー乗り場」といった案内看板（リンク）が立っていますよね。
もし看板がなかったら、あなたはどこへ行けばいいかわからず、立ち尽くしてしまいます。APIの世界も同じです。クライアント（アプリ）に「次はどこへ行けばいいか（どのURLを叩けばいいか）」を、レスポンスの中に「看板」として含めてあげる。これがHATEOASの考え方です。
—
2. 「看板」がないAPIのつらさ
まずは、HATEOASを使わない、少し「不親切なAPI」を見てみましょう。
// 注文情報を取得するAPI
{
"order_id": 12345,
"status": "pending",
"total": 5000
}このレスポンスだけだと、クライアント側は「この注文をキャンセルするには、どのURLにどんなリクエストを送ればいいんだ？」と悩んでしまいます。結局、開発者は仕様書（マニュアル）を必死に読み込み、「きっと /orders/12345/cancel だろう」と推測してコードを書くことになります。
これでは、APIのURL設計を少し変えるだけで、アプリ側も修正が必要になり、とても脆いシステムになってしまいます。
—
3. 「看板」付きAPI（HATEOAS）の美しさ
では、HATEOASを適用して「看板（リンク）」をレスポンスに含めてみましょう。
{
"order_id": 12345,
"status": "pending",
"total": 5000,
"_links": {
"self": { "href": "/orders/12345" },
"cancel": { "href": "/orders/12345/cancel", "method": "POST" },
"payment": { "href": "/orders/12345/pay", "method": "POST" }
}
}見てください！レスポンスの中に _links という項目が追加されましたね。
これがあれば、クライアントは「今は pending だから、cancel や payment のリンクが使えるんだな」と、APIの仕様書を見なくても次に何ができるか判断できるようになります。
これが、HATEOASが「動的な発見（Discovery）」を可能にする仕組みの正体です。
—
4. 実務で活かすためのポイント
現場でHATEOASを実装する際、いくつか意識しておきたい「コツ」があります。
① リンク先はハードコードしない
クライアント側で「URLを文字列として組み立てない」のが鉄則です。レスポンスに含まれた href の値をそのまま使うように設計しましょう。これにより、サーバー側でURLの階層構造を変えても、クライアント側には影響が出なくなります。
② 状態に応じてリンクを出し分ける
例えば、注文が「完了」した後に「支払い」リンクがあっても混乱しますよね。
// 支払い済みの注文の場合
{
"status": "paid",
"_links": {
"self": { "href": "/orders/12345" },
"receipt": { "href": "/orders/12345/receipt" } // 支払いリンクの代わりに領収書リンクを出す
}
}このように、その時のステータスに応じて「今提示すべき選択肢（看板）」だけを動的に表示するのが、HATEOASの真骨頂です。
—
まとめ：ネットワークの恩恵をAPIにも
ネットワークの世界では、パケットがルーターを通過するたびに、次のネクストホップ（次の目的地）をルーターが判断して転送します。HATEOASもこれに似ています。
APIを設計する際は、ぜひ「このレスポンスを受け取ったユーザーは、次に何をしたくなるだろう？」と想像してみてください。そして、その答えとなる「看板」を、さりげなく _links に添えてあげるのです。
最初は少し手間かもしれませんが、この「親切な設計」が、将来のAPI変更に強い、しなやかで美しいシステムを育ててくれます。
皆さんのAPI設計が、使う人にとって迷いのない、心地よいものになりますように。それでは、また次回の深淵でお会いしましょう！
コメント