Zenn
🎮

非エンジニアのためのゲームAPI仕様書超入門

に公開
api設計
tech

TL;DR
ゲームの API 仕様書は「誰でも実装できる詳細設計書」。本記事では API の基礎から最新フォーマット、執筆フロー、チェックリストまで網羅し、**非エンジニアでも“書ける・回せる”**ようになることを目指します。

0. 用語ミニ辞典 — まずはここだけ押さえる！

用語 かんたん説明 例・たとえ
API アプリとサーバが「決まりごと通りに会話」するための取り決め。 スタバの注文票
HTTP Web の郵便屋さん。リクエスト（手紙）とレスポンス（返事）を運ぶ。 郵便局
Endpoint API が待機する「受付窓口」の URL。 https://api.game.com/players
Method 「何をしたいか」を示す動詞。GET=取り出す、POST=作る など。 「注文」「更新」
JSON データを文字列で渡す共通フォーマット。 Excel の行をテキスト化
Schema データの「型」を定めた設計図。 申込書のフォーマット
JWT 「この人はログイン済」を証明するハンコ付きカード。 社員証
OAuth 他サービスに「一時鍵」を渡して代理ログイン。 ホテルのカードキー
Rate Limit API の同時アクセスにかける速度制限。 道路の制限速度
Lint 仕様書の「文法チェッカー」。 校正ツール
Mock Server 実サーバの“替え玉”。先にクライアント開発できる。 ダミー人形
OpenAPI REST API 用の“国語辞典”。JSON/YAML で書く。 新語辞典
AsyncAPI Pub/Sub イベント用の辞典。WebSocket や Kafka 向き。 トランシーバー
GraphQL 欲しいデータを「クエリ」で宣言し取得量を最適化。 回転寿司のタブレット
gRPC 高速・軽量通信を実現するプロトコル。 新幹線

ワンポイント
分からない単語が出てきたら、この表に戻れば大丈夫！

1. API ってなんやねん？

1‑1. リモコンのたとえ

ユーザ操作（ボタン）→ HTTP リクエスト → ゲームサーバ → HTTP レスポンス → 画面更新。
ボタン配置（エンドポイント）、押し方（メソッド）、返ってくる情報（レスポンス）がそろえば実装者は迷わへん。

1‑2. ゲーム開発における API の役割

  • クライアント ⇔ サーバ間通信
  • 他社サービス連携（SNS 投稿、課金基盤 など）
  • 運営ツール（バックオフィス）

2. なぜ「仕様書」が要るのか

観点 目的
実装者目線 迷わずコーディング／テストできる
運営・CS アップデート時の影響範囲を即把握
外部パートナー SDK や連携 API の接続コストを最小化
監査・法務 データ保護・課金フローなどの適合確認

3. API 仕様の主要フォーマット

フォーマット 用途 主な特徴 採用例
OpenAPI (OAS 3.1 / 3.2 β) REST/HTTP JSON/YAML, 豊富なツール群, 生成系 AI との親和性 Fortnite, Minecraft API
AsyncAPI 3.0 Pub/Sub, WebSocket イベント駆動、Kafka などメッセージ基盤向け Valorant Match Events
GraphQL SDL 単一エンドポイント／複合取得 クエリで取得形を宣言、過取得防止 Facebook Gaming
gRPC proto バイナリ通信／高速 HTTP/2, ストリーミング, 型安全 リアルタイム PvP
JSON:API REST 規約セット 統一エラーフォーマット, リンク表現 CMS 系ゲームポータル

最新動向

  • OpenAPI 3.2 は 階層タグ と 自己識別ドキュメント を追加予定（2025 年リリース目標）。
  • Moonwalk プロジェクトが OpenAPI 4.0 の基礎を進行中。時期は未定ながら 2024‑2025 年の議論が活発。
  • AsyncAPI 3.0 が 2023‑12 に正式公開、チャネル再利用やセキュリティ拡張が話題。

4. 仕様書の必須パーツ 10 連発

  1. エンドポイント一覧：動詞ではなく 名詞（/players）
  2. HTTP メソッド：GET/POST/PUT/PATCH/DELETE
  3. パスパラメータ & クエリ：型・制約・例
  4. リクエストボディ：JSON Schema で型定義
  5. レスポンス：成功系と失敗系を必ず対で
  6. エラーモデル：コード／メッセージ／リトライ可否
  7. 認証・認可：JWT／OAuth など方式とフロー
  8. レート制限：X‑RateLimit ヘッダ例
  9. バージョニング：URI vs Header vs Media‑Type
  10. サンプル & エッジケース：正常・異常どちらも

5. 執筆フロー（実例付き）

6. ミニマムサンプル（OpenAPI 3.2 β）

openapi: 3.2.0
info:
  title: Game Inventory API
  version: 0.1.0
paths:
  /players/{playerId}/inventory:
    get:
      summary: プレイヤーのインベントリを取得
      tags: [Players > Inventory]
      parameters:
        - name: playerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Inventory'
components:
  schemas:
    Inventory:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
    Item:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
        name:
          type: string
        quantity:
          type: integer

7. よくある落とし穴と回避策

NG 例 症状 改善ポイント
UI 画面遷移をそのまま API に反映 データ冗長 & 保守困難 ドメイン中心で設計
例外レスポンスが HTML モバイルアプリ側がパース不能 application/json で統一
リソース名に動詞 REST 準拠崩壊 名詞＋メソッドで操作表現

8. ツール & サービス

  • GUI: Swagger Editor, Stoplight Studio
  • Lint: Spectral, Optic
  • Mock: Prism, WireMock
  • テスト: Dredd, Schemathesis
  • CI パイプライン: GitHub Actions + openapi‑generator
  • ドキュメント配信: Redocly, ReadMe

9. 書いた後のチェックリスト

  • 主要ユースケースがカバーされている
  • すべてのレスポンスに error ケースがある
  • 認証フロー図がある
  • レート制限値が具体的
  • データ型と Enum 値が明確

10. 参考文献 & リンク集

  1. OpenAPI Initiative – “Moonwalk 2025 Update”, 2025‑02‑05.
  2. OpenAPI Initiative – “Newsletter December 2024”, 2024‑12‑23.
  3. AsyncAPI Initiative – “AsyncAPI 3.0.0 Release Notes”, 2023‑12‑05.
  4. Excelorithm – “The Future of API Development: AI and New Standards in 2025”, 2025‑01.

Discussion