Skip to main content

REST API 設計・実装ガイド

このガイドについて​

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 ドメインモデル技法エンティティと値オブジェクト、集約と不変条件、消費税額の計算例、境界づけられたコンテキスト
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 で実装する」の見出しの手前までを読み、仕様から先を自分の言語で実装してください
  • 辞書的に使いたい: 上の章立て表から該当する章を直接開いてください

関連ガイド​


それでは はじめに から始めましょう。