LESSON 15分

ストーリー

L2月1で設計原則を学び、自信をつけたあなた。

ある日、チームリーダーの高橋アーキテクトに呼ばれた。

高
高橋アーキテクト
先月の設計原則、よく理解できていたね。次のステップに進もう
あなた
次は何を学ぶんですか？
あ
高
高橋アーキテクト
APIの設計だ。ソフトウェアの世界では、システム同士が会話する必要がある。その会話のルール、つまり”契約”を設計するのがAPI設計者の仕事だ
あなた
契約…ですか？
あ
高
高橋アーキテクト
そうだ。良い契約は両者を幸せにする。悪い契約は混乱と障害を生む。この1ヶ月で、君には”良い契約”を書けるエンジニアになってもらう

APIとは何か

API（Application Programming Interface）の本質

APIとは、ソフトウェア同士が通信するためのインターフェースです。日常に例えると、レストランのメニューのようなものです。

sequenceDiagram
    participant C as お客さん（クライアント）
    participant M as メニュー（API）
    participant K as キッチン（サーバー）

    C->>M: 「カレーください」
    M->>K: 注文を伝える
    K-->>M: 料理を返す
    M-->>C: カレーが届く
  • メニュー（API仕様）: 何を注文できるか、どう注文するかを定義
  • お客さん（クライアント）: APIを利用する側
  • キッチン（サーバー）: リクエストを処理して結果を返す側

Web APIの種類

// 1. REST API - リソース指向
// GET /api/users/123
const user = await fetch('/api/users/123');

// 2. GraphQL - クエリ指向
// POST /graphql
const result = await fetch('/graphql', {
  method: 'POST',
  body: JSON.stringify({
    query: `{ user(id: 123) { name, email } }`
  })
});

// 3. gRPC - RPC指向（バイナリプロトコル）
// Protocol Buffers でスキーマ定義

// 4. WebSocket - 双方向通信
const ws = new WebSocket('ws://example.com/chat');

なぜAPI設計が重要なのか

APIは「契約」である

// この関数のシグネチャは「契約」
// 引数と戻り値の型が、呼び出し側との約束事
interface UserAPI {
  // 「IDを渡せば、Userオブジェクトを返す」という契約
  getUser(id: string): Promise<User>;

  // 「Userデータを渡せば、作成されたUserを返す」という契約
  createUser(data: CreateUserInput): Promise<User>;
}

良い契約の3条件

条件説明例
明確性曖昧さがなく、誰が読んでも同じ解釈になるGET /users/{id} は「IDでユーザーを取得」
安定性一度公開したら簡単に変えないバージョニング戦略で変更を管理
一貫性全体を通して同じパターン・規則に従う命名規則、エラー形式の統一

L2月2の全体像

6つのステップ（合計20時間）

Stepテーマ時間主なスキル
1API設計の世界へようこそ2hREST基礎、ベストプラクティス
2RESTful API設計の深淵4hリソース設計、認証、レート制限
3OpenAPIで契約を定義しよう3hOpenAPI仕様、スキーマ、コード生成
4GraphQLの可能性を探ろう5hQuery, Mutation, スキーマ設計
5APIバージョニングと進化戦略4hバージョニング、後方互換性、Gateway
6最終試験2h総合演習 + 卒業クイズ

学習のコツ

L2レベルで意識すること

  1. 利用者視点で考える: APIの設計者は、常に利用者（開発者）の立場で使いやすさを考える
  2. 契約を明文化する: 口頭の約束ではなく、仕様書として残す（OpenAPI）
  3. 変更に強い設計: 将来の変更を見越して、拡張性のある設計を心がける
  4. 実例に学ぶ: GitHub API、Stripe API等、優れたAPIの設計パターンを観察する

高橋アーキテクトからのアドバイス

「APIは一度公開すると、簡単には変えられない。だからこそ、最初の設計が肝心だ。 “動けばいい”ではなく、“使いやすく、変化に強い”APIを目指してほしい」 — 高橋アーキテクト

まとめ

ポイント内容
APIの本質ソフトウェア同士の通信インターフェース
APIは契約明確性・安定性・一貫性の3条件が重要
L2月2の目標REST、GraphQL、OpenAPIを使いこなし、良い契約を設計できるようになる
前提知識L2月1の設計原則（SOLID、DRY、KISS等）

チェックリスト

  • APIの基本概念を理解した
  • Web APIの種類（REST, GraphQL, gRPC, WebSocket）を把握した
  • 良い契約の3条件を理解した
  • L2月2の全体像を把握した

次のステップへ

準備はできましたか？

次のセクションでは、最も広く使われているAPIスタイルである REST の基本原則を学びます。 リソース指向、HTTPメソッド、ステータスコード — これらの理解がAPI設計の土台になります。

API設計者への第一歩を踏み出しましょう。

推定読了時間: 15分