2026/06/23

スマホアプリ向けAPIでのHATEOAS設計は本当に悪手？実務的な妥協点と部分的採用のススメ

スマホアプリ向けAPIでのHATEOAS設計は本当に悪手？実務的な妥協点と部分的採用のススメ

スマホ向けAPIの設計をしていると、「URL変更によるアプリの強制アップデートをどう避けるか」とか、「期限付きトークンの管理をどうスマートに行うか」といった問題にぶつかる。この記事では、RESTの最上位原則とも言われるHATEOAS（Hypermedia as the Engine of Application State）をスマホアプリ向けAPIに適用する際の実務上のメリットやデメリット、そして完全採用で挫折しないための部分的採用という落としどころについて解説する。理想論に偏らず、クライアント開発者の実装コストやトラブル対処まで含めた現実的なAPI設計のヒントが得られると思う。

HATEOASって実際どうなんだろう？REST成熟度と実務のギャップ

HATEOASは、レスポンスの中に次に呼ぶべきAPIのリンク（URL）を埋め込んでおき、クライアントがそのリンクを動的に辿ることでアプリケーションの状態を遷移させる設計思想だ。よくREST APIの定義として引き合いに出される「Richardson Maturity Model（リチャードソン成熟度モデル）」では、最高レベルであるLevel 3に位置付けられている。

実務で使われるWeb APIのほとんどは、リソース単位のURL設計（Level 1）やHTTPメソッドの使い分け（Level 2）で止まっており、Level 3のHATEOASまでしっかりと実装している例は稀なんだよね。なぜなら、「クライアントとサーバーの結合度を極限まで下げる」という理想に対して、実装やメンテにかかるコストが明らかに高すぎると思われているからだ。特に仕様変更のスピードが速いスマホアプリの開発現場では、ドキュメントの更新が追いつかない中で動的なURLパースを入れるのは敬遠されがちだったりする。

ファイルDLフローにおけるHATEOASのレスポンス設計例

言葉だけで考えてもピンとこないため、具体的なユースケースを想定してレスポンス例を見てみよう。今回は「ファイル一覧取得 → 詳細取得 → ファイルダウンロード（DL） → ダウンロード完了確認（ACK）」という段階的なフローをHATEOASライクに表現してみた。

1. 一覧取得APIのレスポンス

まずはファイルの一覧を取得する。この段階で、各アイテムの詳細APIのURLや、ページネーションの次のページのURLを `_links` という標準的なキーの下に埋め込んで返す。

{
  "items": [
    {
      "id": "abc123",
      "name": "document.pdf",
      "size": 1048576
    }
  ],
  "_links": {
    "self": { "href": "/files" }, // 自分自身のエンドポイント
    "detail": { "href": "/files/abc123" }, // 詳細取得のための動的なリンク
    "next_page": { "href": "/files?page=2" } // クライアント側でクエリを組み立てさせないための次ページリンク
  }
}

2. 詳細取得APIのレスポンス

詳細APIを叩くと、ファイルのメタデータに加えて、一時的なダウンロードトークンを含んだ有効期限付きの署名付きURLが `download` リンクとして降ってくる。

{
  "id": "abc123",
  "name": "document.pdf",
  "version": "2.1.0",
  "checksum": "sha256:deadbeef...",
  "_links": {
    "self": { "href": "/files/abc123" },
    "download": { "href": "/files/abc123/download?token=xyz789&expires=1719100000" }, // 期限付きダウンロードURL
    "list": { "href": "/files" } // 一覧へ戻るためのリンク
  }
}

3. ファイルダウンロードAPI（バイナリ送信）

上記の `download` のリンク先へGETリクエストを送ると、ファイル本体がバイナリで返却される。しかし、バイナリデータ（`application/octet-stream`）のボディ部にはJSONリンクを含めることができない。そこで、レスポンスヘッダーを利用して次の完了確認（ACK）用のURLを受け渡す。

HTTP/1.1 200 OK
Content-Type: application/octet-stream
X-ACK-URL: /files/abc123/ack?token=xyz789&download_id=dl_001
Content-Length: 1048576

(バイナリデータ...)

4. ダウンロード完了確認（DL ACK）API

クライアントはヘッダーから抽出した `X-ACK-URL` に対し、ダウンロードが正常に終わったことを通知するPOSTを送る。完了後の遷移先リンクもレスポンスに含まれている。

POST /files/abc123/ack?token=xyz789&download_id=dl_001

{
  "status": "ok",
  "_links": {
    "detail": { "href": "/files/abc123" },
    "list": { "href": "/files" }
  }
}

設計思想の比較：なぜスマホ向けでは敬遠されるのか？

この設計のメリットは明らかで、クライアント側が「次に呼ぶべきAPIのパス」を一切知らなくていい点にある。サーバー側でエンドポイントの設計を変えたり、ダウンロード処理のドメインを別サーバー（CDNなど）へ逃がしたりしても、クライアントのコードを修正して強制アップデートをかける必要がない。また、状態管理がサーバー側で一元化されるため、「特定の状態のときだけダウンロードボタンを活性化する」といった制御が、リンクの有無だけで表現できる。

しかし、スマホアプリの開発でこれが敬遠されるのは、クライアント側の実装が複雑化するからだ。URLをソースコードに文字列定数として定義する（ハードコーディングする）方が圧倒的に直感的だし、多くのモバイル開発チームはその手法に慣れている。また、全レスポンスにリンク情報が乗り続けるため通信容量が微増することや、URLがクエリパラメータなどで動的に変化するためにHTTPキャッシュやローカルキャッシュのキー設計が非常に難しくなるというデメリットもある。

遭遇しがちなトラブルと解決策：OpenAPIスキーマとの相性問題

HATEOASを実務で導入しようとして自分が一番困ったのが、OpenAPI（Swagger）を使った静的なAPIスキーマ定義とクライアントコード自動生成（OpenAPI Generatorなど）との食い合わせの悪さだった。

OpenAPIは、基本的に「どこのURLにどんなスキーマのデータを送れば、何が返ってくるか」を静的に定義するツールだ。しかし、HATEOASのようにURLがレスポンスの値として動的に降ってくる設計だと、クライアント生成ツールが動的な `_links` のパース処理をうまく型定義できないという問題が起きる。特にSwiftやKotlinのコードジェネレータを使うと、レスポンスのオブジェクトがネストする中で循環参照が発生したり、ジェネリクスが解釈できずにコンパイルエラーを吐き出すエラーに直面することがある。

この根本原因は、生成されるモデル定義において、動的リンクを示す `href` のオブジェクトと静的なリソース定義を同じスキーマで表現しようとすることにある。このトラブルを解決するには、API仕様書（yaml/json）側で `_links` 部分を共通のコンポーネント（共通スキーマ）として定義し、かつクライアント側ではURLの解決だけを行う「リンクパーサー」をジェネレータの自動生成対象から除外して別クラスとして手動で定義し、疎結合に分離してパースするのが確実だ。以下のような定義ファイルを切り出しておくことで、コード生成時のエラーを綺麗に防ぐことができた。

# OpenAPI定義ファイルでの共通リンクターゲットの定義例
components:
  schemas:
    LinkObject:
      type: object
      properties:
        href:
          type: string
          format: uri
          description: "次に遷移するAPIの相対パスまたは絶対URL"
    ResourceLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/LinkObject'
        next:
          $ref: '#/components/schemas/LinkObject'

実務での落としどころ：部分的HATEOASの推奨

完全なHATEOASの実装は、学習コストやスキーマ定義のオーバーヘッドを考えると、多くの場合オーバーエンジニアリングになってしまう。だからこそ、実務では**「部分的HATEOAS」**を落としどころにするのがおすすめだと思う。

具体的には、静的なエンドポイント（例: `/files` や `/files/{id}`）はクライアント側で通常通りハードコードして扱い、今回のような「一時的なDLトークン付きURL」や「DL後の通知先（ACK URL）」などのように、状態や時間によって動的に生成しなければならないURLだけをレスポンスに含めるという設計だ。以下のように、リンク専用の `_links` という構造を持たせるのではなく、シンプルなフィールドとして返すのが最も破綻しにくい。

{
  "file_id": "abc123",
  "download_url": "https://cdn.example.com/files/abc123/download?token=xyz789&expires=1719100000",
  "ack_url": "/api/v1/files/abc123/ack?token=xyz789&download_id=dl_001",
  "expires_at": 1719100000
}

これならOpenAPIでの型定義も非常にシンプルで済むし、クライアント側も通常のJSONパースと同様のロジックで対応できる。動的に変わる重要なURL管理のメリットを享受しつつ、実装コストを最小限に抑えることができる実用的な折衷案だと思う。

まとめ

  • HATEOASはAPIレスポンスに次の遷移先URLを含める設計で、RESTの最高成熟度に相当する。
  • サーバー側でURLのルールや状態制御を一元化できるため、クライアントの変更耐性が上がるのが最大のメリット。
  • 一方で、クライアント側の実装負荷やOpenAPIなどのツールチェーンとの相性が悪いという実務上の大きな課題もある。
  • 解決策として、期限付きURLやACK通知先などの動的なパスにだけ絞ってレスポンスやヘッダーに含める「部分的HATEOAS」が実務の落としどころとして最適。
-