このガイドについて
REST API の設計と実装を、1 つの題材で要件から運用まで通して学ぶ全 50 章のガイドです。Web API を初めて作る人が、HTTP の仕組みから始めて、設計の判断を自分で説明できる形で注文 API を作れることを目指します。
題材は EC サイトの注文システムです。最初の周回では注文の作成と取得だけを扱います。要件とドメインモデルを書き、リソースと JSON の形とエラーを決めて OpenAPI の仕様にし、モックで確かめてから TypeScript で実装して PostgreSQL に保存します。2 周目からは、商品の一覧・注文の取り消し・認証・Webhook・API の版の変更と機能を 1 つずつ足し、そのたびに同じ順で設計から実装までを回します。
- 仕様を先に書く: 実装の前に OpenAPI で仕様を書き、lint とモックで確かめます (design-first)。実装を先に書いて仕様を生成するやり方 (code-first) とは、1 周目の終わりで比べます
- 設計の技法もこの中で学ぶ: 要件の整理・イベントストーミング・集約・テーブル設計・クラス設計を、題材に要る範囲で基礎から扱います
- 実務の道具: Swagger UI・Redocly CLI・Prism・Bruno・Schemathesis・oasdiff を、使う場面の章で導入します
- 動かして確かめた例: 記事の curl と応答、コマンドと出力は、サンプルリポジトリのテストで実行し、記事に載せたものと一致することを確かめています
- 版: OpenAPI 3.1、Node.js 26、TypeScript 6.0 を対象とします
ガイドの構造
8 部構成です。第 1 部は言語に依存しない設計の部で、他の言語で実装する人もここまでは同じ順で読めます。
章立て
第 1 部から順に公開しており、未公開の章は「執筆中」と書いています。kind の列は章の種類です。次の 4 つがあります。
- 設計: 言語に依存しない設計の章。TypeScript のコードを読まずに追えます
- 技法: 要件・ドメインモデル・テーブル・クラスの設計の技法を扱う章
- 実装: TypeScript のコードが主の章
- 設計と実装: 1 つの機能で設計から実装までを回す章。「TypeScript で実装する」の見出しの手前までで設計がそろいます
第 1 部 1 周目の設計: 注文の作成と取得を、仕様とモックにする
注文の作成と取得について、要件から OpenAPI の仕様とモックまでを作ります。
| 章 | kind | 扱うこと |
|---|
| 01 はじめに | 設計 | このガイドで作る注文 API、design-first の 1 周、kind ごとの読み方、Node.js と curl の用意、サンプルリポジトリと tag |
| 02 HTTP の仕組み | 設計 | クライアントとサーバー、URL、リクエストとレスポンスの形、curl の使い方、ヘッダ、JSON とメディアタイプ、ステートレス |
| 03 メソッドとステータスコード | 設計 | メソッドの意味、安全と冪等、ステータスコードの分類とよく使うコード、Location と Allow、HEAD と OPTIONS |
| 04 要件の整理 | 技法 | ユーザーストーリーと受け入れ条件、ユースケース記述、画面と API の受け持ち、1 周目に入れないもの |
| 05 ドメインを探る | 技法 | イベントストーミングの付箋と手順、注文のボード、ユビキタス言語と用語集 |
| 06 ドメインモデル | 技法 | エンティティと値オブジェクト値オブジェクト (Value Object)識別子ではなく保持する値そのもので同一性が決まるオブジェクト。生成後は変更せず、不正な値をコンストラクタで弾く使い方をする。、集約と不変条件不変条件 (Invariant)そのオブジェクトが存在する間、常に成り立っていなければならない条件。派生クラスはこれを弱められない。、消費税額の計算例、境界づけられたコンテキスト |
| 07 REST の考え方 | 設計 | RPC 風とリソース風、REST の制約、統一インターフェース、Richardson 成熟度モデル |
| 08 リソースの設計 | 設計 | 集約とコマンドからリソースを見つける、URL の命名、コマンドをメソッドに写す、エンドポイントの一覧 |
| 09 表現の設計 | 設計 | キーの命名、ID・金額・日時・状態の表し方、null と省略、リクエストとレスポンスの形、Content-Type と Accept |
| 10 エラーの設計 | 設計 | 4xx と 5xx、400 と 422、在庫不足のコード、Problem Details (RFC 9457)、問題の種類の表 |
| 11 OpenAPI | 設計 | OpenAPI 3.1 の文書の構造、JSON Schema 2020-12、$ref と components、Swagger UI で読む |
| 12 仕様の lint | 設計 | Redocly CLI の lint と自前の規則、API の設計ガイドライン、仕様の分割と束ね、Redoc の文書 |
| 13 モック | 設計 | Prism のモック、Prefer ヘッダ、curl と Bruno で呼ぶ、受け入れ条件をモックで確かめる |
第 2 部 1 周目の実装: 仕様から動かし、DB なしで照合する
| 章 | kind | 扱うこと |
|---|
| 14 仕様からルートを作る | | 執筆中 |
| 15 リクエストとレスポンスの検証 | | 執筆中 |
| 16 クラス設計 | | 執筆中 |
| 17 集約を実装する | | 執筆中 |
| 18 層と依存の向き | | 執筆中 |
| 19 失敗を HTTP に写す | | 執筆中 |
| 20 テストの分担と仕様との照合 | | 執筆中 |
第 3 部 1 周目の永続化: PostgreSQL に保存して 1 周を閉じる
| 章 | kind | 扱うこと |
|---|
| 21 テーブル設計 | | 執筆中 |
| 22 制約とマイグレーション | | 執筆中 |
| 23 永続化 | | 執筆中 |
| 24 トランザクション | | 執筆中 |
| 25 1 周目の振り返り | | 執筆中 |
第 4 部 2・3 周目: 商品を探して見る、注文を取り消して変える
| 章 | kind | 扱うこと |
|---|
| 26 一覧の設計 | | 執筆中 |
| 27 一覧の実装 | | 執筆中 |
| 28 キャッシュ | | 執筆中 |
| 29 状態を変える操作 | | 執筆中 |
| 30 更新の衝突 | | 執筆中 |
| 31 送り直し | | 執筆中 |
第 5 部 4 周目: 会員と管理者の認証・認可・レート制限
| 章 | kind | 扱うこと |
|---|
| 32 認証の設計 | | 執筆中 |
| 33 認証の実装 | | 執筆中 |
| 34 オブジェクト単位の認可 | | 執筆中 |
| 35 機能単位の認可 | | 執筆中 |
| 36 レート制限 | | 執筆中 |
第 6 部 5 周目の非同期と連携: 決済・連携先・商品画像・取り込み・一括の入荷
| 章 | kind | 扱うこと |
|---|
| 37 外部の API を呼ぶ | | 執筆中 |
| 38 Webhook の受信 | | 執筆中 |
| 39 Webhook の送信 | | 執筆中 |
| 40 ファイルのアップロード | | 執筆中 |
| 41 時間のかかる処理 | | 執筆中 |
| 42 一括操作 | | 執筆中 |
第 7 部 6 周目: 公開した API を変える
| 章 | kind | 扱うこと |
|---|
| 43 API の変更 | | 執筆中 |
| 44 廃止の告知 | | 執筆中 |
| 45 バージョニング | | 執筆中 |
| 46 契約テスト | | 執筆中 |
第 8 部 運用と振り返り: ログ・セキュリティの点検・REST の外側
| 章 | kind | 扱うこと |
|---|
| 47 ログと追跡 | | 執筆中 |
| 48 セキュリティの点検 | | 執筆中 |
| 49 REST の外側 | | 執筆中 |
| 50 おわりに | | 執筆中 |
対象読者
- Web API を作るのが初めての人。HTTP の仕組みもこのガイドで説明します
- API を作ったことはあるが、URL・ステータスコード・エラーの形を何を根拠に決めればよいか迷う人
- OpenAPI や Swagger UI を実務で使い始める人
前提知識
| 必須度 | 知識 | 補足 |
|---|
| 必須 | 何らかの言語で、変数・条件分岐・繰り返し・関数を書いたことがある | 全章 |
| 必須 | ターミナルの基本操作 | 第 1 章からコマンドで curl とテストを動かします |
| 推奨 | Git でリポジトリを clone できる | 第 1 章でサンプルリポジトリを取得します |
| 推奨 | TypeScript の基本 (型の注釈・関数・クラス) | 第 2 部から。TypeScript ガイド で補えます |
| 推奨 | SQL の SELECT / INSERT / UPDATE が読める | 第 3 部から。書けなくてかまいません |
| 不要 | HTTP・Web API・OpenAPI の経験 | 本ガイドで基礎から解説します |
推奨される読み方
- Web API が初めて: 第 1 章から順に読み、curl とコマンドをサンプルリポジトリで動かしながら進めてください。動かし方は第 1 章にあります
- TypeScript 以外の言語で実装する: 第 1 部はすべて読みます。第 2 部からは、設計と技法の章と、設計と実装の章の「TypeScript で実装する」の見出しの手前までを読み、仕様から先を自分の言語で実装してください
- 辞書的に使いたい: 上の章立て表から該当する章を直接開いてください
関連ガイド
それでは はじめに から始めましょう。