このlessonをすべて読み終えると、以下の3つを自信を持って実践できます。

• ▸✅ RESTの6原則 + Stateless · Cacheable · Uniform Interface
• ▸✅ REST vs GraphQL vs gRPCの選択
• ▸✅ OpenAPI (Swagger) 仕様の作成

学習目標をチェックリストとして手元に置き、すべてに答えられるようになったらlessonを閉じましょう。

REST (Roy Fielding, 2000) — Representational State Transfer

6原則:
1. Client-Server — 関心の分離
2. Stateless — サーバーは状態を持たない（各リクエストは独立）
3. Cacheable — レスポンスをキャッシュ可能
4. Uniform Interface — 標準メソッド（GET · POST · PUT · DELETE）
5. Layered — クライアントは直接接続かプロキシ経由かを知らない
6. Code on Demand（任意） — 実行可能コード（例：JavaScript）の送信が可能

RESTful URL設計:

良いレスポンス設計:

{
  "data": { "id": 42, "name": "Hong Gildong" },
  "meta": { "version": "v1", "timestamp": "2025-..." }
}

// エラー
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "ユーザーが見つかりません",
    "details": { "id": 42 }
  }
}

バージョニング — 3つのアプローチ:

• ▸URL: /v1/users（最も一般的）
• ▸ヘッダー: Accept: application/vnd.api+json;version=1
• ▸クエリ文字列: /users?version=1

HATEOAS（RESTfulの究極形）:

• ▸レスポンスに次に可能なアクションへのリンクを含める
• ▸実用性が低く、ほとんど使われない

REST vs GraphQL vs gRPC — 3つのパラダイム:

GraphQL — Facebook (2015):

query {
  user(id: 42) {
    name
    email
    orders(last: 5) {
      id
      total
    }
  }
}

• ▸1回のリクエストで必要なものだけ取得
• ▸1つのバックエンドで多様なクライアント（Web · モバイル · アプリ）に対応
• ▸デメリット: キャッシングとレート制限が複雑

gRPC — Google (2015):

• ▸Protobufスキーマ定義:

service UserService {
  rpc GetUser (UserId) returns (User);
  rpc StreamUsers (Filter) returns (stream User);
}
message User { int64 id = 1; string name = 2; }

• ▸コードの自動生成（Java · Go · Python · ...）
• ▸双方向ストリーミング
• ▸内部MSAの標準（Google · Netflix · Uber）
• ▸ブラウザではgRPC-Webが必要

使い分けの指針:

• ▸🟢 REST: 一般的な外部API · モバイル · Web
• ▸🟢 GraphQL: 複雑なUI · 多様なクライアント
• ▸🟢 gRPC: 内部MSA · リアルタイムストリーミング

JSON (JavaScript Object Notation, 2001) — データ交換の標準:

{
  "name": "Hong Gildong",
  "age": 28,
  "hobbies": ["coding", "reading"],
  "address": {
    "city": "Seoul",
    "zip": "06164"
  },
  "active": true,
  "registered_at": null
}

データ型:

• ▸string: "text" (UTF-8)
• ▸number: 42, 3.14, 1e10（整数と小数の区別なし）
• ▸boolean: true, false
• ▸null
• ▸array: [1, 2, 3]
• ▸object: {"key": "value"}

注意点:

• ▸❌ コメント不可（JSON5・JSONCは別形式）
• ▸❌ 末尾カンマ不可
• ▸❌ シングルクォート不可（ダブルクォートのみ）
• ▸❌ undefined 不可
• ▸✅ 整数の精度: JS Numberは2^53以下のみ安全 → 大きなIDは文字列推奨

API呼び出しフロー（ブラウザからDBまで）:

1. JS: fetch('/api/users/42')
   └─ ブラウザのFetch API

2. ブラウザ:
   - DNSルックアップ（codemaster40.com → IP）
   - TCP 3ウェイハンドシェイク + TLSハンドシェイク
   - HTTP/2またはHTTP/3でリクエスト送信

3. CDN（CloudFrontなど）:
   - 静的キャッシュのヒット? → 即時レスポンス
   - ミス → オリジンへ転送

4. ロードバランサー（ALB · Nginx）:
   - どのサーバーへ?（round-robin · least-conn）
   - SSLターミネーション（TLS → 内部は平文）

5. アプリケーションサーバー（Node · Spring）:
   - ミドルウェア（認証 · ロギング · rate limit）
   - ルーター → コントローラー
   - ビジネスロジック

6. キャッシュ（Redis）:
   - ヒット → 即時返却
   - ミス → DBへ

7. データベース（Postgres · MySQL）:
   - クエリ実行（EXPLAINの結果に従って）
   - 結果 → キャッシュに保存 → レスポンス返却

8. 逆順でレスポンス
   DB → App → LB → CDN → ブラウザ → JS

各ステップが最適化ポイント — 1つのステップが遅ければ全体が遅くなる。

このlessonの概念を理解すれば、AIに具体的に指示を出せるようになります。漠然とした「直して」ではなく、語彙を持ったリクエスト — それがトークン節約の出発点です。

• ▸「このREST APIをGraphQLに変換した場合のメリット・デメリットを比較してください」
• ▸「このAPIのOpenAPI (Swagger) 仕様を作成してください」

なぜこれがトークンを減らすのか

概念を知らないと、AIの回答を受け取っても「それはどういう意味ですか?」と再度聞き直す必要があります。その「聞き直し」がトークンを消費します。概念を一度しっかり覚えておけば、会話が一度で完結します。