はじめに: design-first で注文 API を作る
このガイドでは、EC サイトの注文 API を作りながら、REST API の設計と実装を学びます。要件を書くところから始め、ドメインモデルを描き、URL や JSON の形やエラーを決め、OpenAPI で仕様を書き、モックで確かめてから TypeScript で実装します。
この章では、作るものと進め方を示したあと、章の読み方を説明し、開発環境とサンプルリポジトリを用意します。章の終わりには、サンプルリポジトリのテストを手元で動かせる状態になります。
このガイドで作るもの
題材は EC サイトの注文システムです。最初に扱う概念は次の 4 つです。
- 注文: 1 回の購入の依頼です。1 つ以上の注文明細を持ちます
- 注文明細: 注文に含まれる 1 行です。どの商品を、いくつ、いくらで買うかを持ちます
- 商品: 注文できる品物の 1 種類です
- 在庫: 商品ごとに持つ、注文に引き当てられる数量です
注文する人を購入者と呼びます。購入者が注文すると、注文明細の数量をその商品の在庫から差し引きます。この操作が引き当てです。
このガイドは、同じ注文システムに機能を少しずつ足していきます。最初の周回で作るのは、次の 2 つの操作だけです。
- 注文する: 購入者が商品と数量を選んで注文する。在庫が足りれば引き当てて注文を受け付け、足りなければ断る
- 注文を確かめる: 受け付けた注文の内容を、注文の ID で取り出す
最初の周回には、ログインも、商品の一覧も、注文の取り消しもありません。範囲を絞るのは、1 つの機能で要件から実装までを一度通し、各段で何を決めたかを見通しやすくするためです。何を入れて何を入れないかは、要件を整理する章で決めます。
Web API とは何か
EC サイトのスマートフォンのアプリで「注文する」を押すと、アプリは店のサーバーに「この商品を 2 個」と伝え、サーバーは「注文を受け付けました。注文の番号はこれです」と答えます。アプリとサーバーは別のプログラムで、多くは別の会社やチームが作ります。それでも話が通じるのは、何をどの形で送れば何が返ってくるかを、両者が前もって決めているからです。
この取り決めと、それに従って答えるサーバーの側の仕組みを、API (Application Programming Interface) と呼びます。API の向こう側の実装 (データベースの形や、在庫をどう数えるか) は、アプリからは見えません。アプリが当てにできるのは取り決めだけです。
Web のページを読むのと同じ通信の仕組みを使う API を、Web API と呼びます。その仕組みは次の章で見ます。このガイドで作るのは、注文システムの Web API です。
API の取り決めは、一度公開すると簡単には変えられません。API を使うアプリは今の取り決めに合わせて作られ、購入者の手元ですでに動いているからです。だから、取り決めを決める段で時間をかける価値があります。このガイドが実装より前の設計に多くの章を使うのは、そのためです。
design-first の進め方
API を作る進め方は、大きく 2 つに分かれます。
- design-first: 先に API の仕様を書き、仕様で合意してから実装する
- code-first: 先に実装を書き、実装のコードから仕様を生成する
このガイドは design-first で進めます。仕様が先にあると、API を呼ぶアプリを作るチームは、サーバーの実装を待たずに、仕様から作ったモックを相手に開発を始められます。仕様は読める文書なので、実装の言語を知らない人もレビューに加われます。code-first と比べるのは、最初の周回の実装が終わった後 (第 3 部の終わり) です。
1 つの機能について、このガイドは次の順に進めます。これを 1 周と呼びます。
| 段 | すること |
|---|---|
| 要件 | 誰が何のためにどう使うかと、受け入れる条件を書く |
| ドメインモデル | 注文や在庫がどんな規則を持つかを整理する |
| リソース・表現・エラーの設計 | URL とメソッド、JSON の形、失敗の返し方を決める |
| OpenAPI の仕様 | 決めたことを、機械が読める仕様の形式で書く |
| lint | 仕様が書き方の決まりに沿っているかを道具で検査する |
| モック | 仕様から、決まった応答を返す仮のサーバーを立て、要件の受け入れ条件を確かめる |
| 実装 | 仕様どおりに動くサーバーを TypeScript で書く |
| 仕様との照合 | 実装の応答が仕様に合っているかを、テストで確かめる |
最後の照合を省くと、design-first の利点が残りません。仕様と実装は別々に書くので、放っておくとずれていきます。API を使う人が当てにできるのは、仕様と実装が一致し続けている間だけです。
周回と部
最初の周回 (注文の作成と取得) は、1 周が長いので 3 つの部に分けます。設計の部・実装の部・データベースに保存する部です。2 周目からは、1 つの部の中で 1 周から 2 周を回します。
第 1 部 (この章から 13 章まで) は、注文の作成と取得について、要件から OpenAPI の仕様とモックまでを作ります。プログラミングの言語に依存しない部なので、TypeScript 以外の言語で実装する人も、第 1 部の仕様から自分の言語で実装に入れます。
章の種類と読み方
章には次の 4 つの種類があります。ガイドの目次の章立ての表の kind の列に書いてあります。
| 種類 | 中身 | TypeScript のコード |
|---|---|---|
| 設計 | URL・JSON・エラー・仕様など、言語に依存しない設計 | 出てこないか、章末の節にまとめる |
| 技法 | 要件の整理・ドメインモデル・テーブル・クラスの設計の技法 | 本文には主に出てこない (クラス設計などの章は出てくる)。文書を確かめるテストのコードは章末の節にまとめる |
| 実装 | 設計したものを TypeScript で書く | 章の中心 |
| 設計と実装 | 1 つの機能で設計から実装までを回す | 「TypeScript で実装する」の見出しから後 |
読み方は、目的で選んでください。
- Web API が初めて: この章から順に読み、記事の curl とコマンドをサンプルリポジトリで動かしながら進めてください
- TypeScript 以外の言語で実装する: 第 1 部はすべて読みます。第 2 部からは、設計と技法の章と、設計と実装の章の「TypeScript で実装する」の見出しの手前までを読み、仕様から先を自分の言語で実装してください
- 辞書的に使いたい: 目次の章立ての表から、知りたい話題の章を開いてください
第 1 部では、2・3・7 章で HTTP の観察のために小さなサーバーを動かします。また 4 章からは、要件・モデル・仕様の文書が食い違わないことを、サンプルリポジトリのテストで確かめます。サーバーのコードは章末の節「この章のサーバーのコード」に、テストのコードは「この章のテストのコード」にまとめたので、本文は TypeScript を読まずに追えます。
前提知識
| 必須度 | 知識 | 補足 |
|---|---|---|
| 必須 | 何らかの言語で、変数・条件分岐・繰り返し・関数を書いたことがある | 全章 |
| 必須 | ターミナルの基本操作 | 第 1 章からコマンドで curl とテストを動かします |
| 推奨 | Git でリポジトリを clone できる | 第 1 章でサンプルリポジトリを取得します |
| 推奨 | TypeScript の基本 (型の注釈・関数・クラス) | 第 2 部から。TypeScript ガイド で補えます |
| 推奨 | SQL の SELECT / INSERT / UPDATE が読める | 第 3 部から。書けなくてかまいません |
| 不要 | HTTP・Web API・OpenAPI の経験 | 本ガイドで基礎から解説します |
開発環境を用意する
第 1 部で使うのは、Node.js・curl・Git・エディタの 4 つです。データベースと Docker は、要る部で用意します。
このガイドのコマンドとサンプルリポジトリのテストは、macOS か Linux のシェル (bash か zsh) で動かす前提です。テストは bash・find・ps を使います。Windows では、WSL (Windows Subsystem for Linux) の Ubuntu などを入れ、Node.js も WSL の中に入れて、WSL のシェルでコマンドを打ってください。
Node.js 26
サンプルリポジトリのテストと道具 (OpenAPI の lint・モック・Swagger UI) は Node.js で動きます。使う版は Node.js 26 です。26 は 2026 年 10 月から LTS (長期サポート版) で、サポートは 2029 年 4 月まで続きます。
入れ方は、Node.js の公式サイトのインストーラか、版を切り替えられる道具 (nvm・fnm・mise など) のどれでもかまいません。サンプルリポジトリには .nvmrc があり、版を切り替えられる道具の多くはこのファイルを読んで 26 を選びます。
入れたら、版を確かめます。
node --version
v26.13.0
v26 で始まっていれば足ります。
curl
このガイドは、API を呼ぶのに curl を使います。curl は、コマンドラインから HTTP のリクエストを送る道具です。macOS と多くの Linux には最初から入っています。
curl --version
curl 8.18.0 (x86_64-pc-linux-gnu) libcurl/8.18.0 OpenSSL/3.5.5 zlib/1.3.1 brotli/1.2.0 zstd/1.5.7 libidn2/2.3.8 libpsl/0.21.2 libssh2/1.11.1 nghttp2/1.68.0 librtmp/2.3 mit-krb5/1.22.1 OpenLDAP/2.6.10
このガイドの curl の例は、bash と zsh の書き方 (単一引用符で囲んだ値、行末の \ で次の行に続ける書き方) で書いています。
Git とエディタ
Git はサンプルリポジトリの取得と、章ごとの状態の切り替えに使います。エディタは何でもかまいません。第 1 部では YAML (OpenAPI の仕様) と Markdown を、第 2 部からは TypeScript を書きます。VS Code を使う場合は、OpenAPI の章で、仕様の YAML に補完を効かせる設定を扱います。
サンプルリポジトリ
このガイドで作る要件の文書・仕様・モック・コードは、サンプルリポジトリ rest-api-order にあります。取得して、依存するパッケージを入れます。
git clone https://github.com/rasshii/rest-api-order.git
cd rest-api-order
npm ci
npm ci は、package-lock.json に書かれた版のとおりにパッケージを入れます。記事に書いた道具の版と、手元で動く版がそろいます。
章の tag
サンプルリポジトリは、章ごとに tag を付けています。tag rest-NN は、第 NN 章まで読んだ時点のリポジトリです。公開の後に直したときは、直した章と、その直しを含む後の章に rest-NN-r2 を付けます (もう一度直したら rest-NN-r3、以後も番号を 1 つずつ増やします)。同じ章に r の付いた tag があるときは、番号のいちばん大きい tag が、その章の今の状態です。記事に載せたファイルの中身とコマンドの結果は、その章の今の状態の tag のものです。
ある章の状態から始めたいときは、その章の今の状態の tag に切り替えます。tag の一覧は git tag --list 'rest-*' で見られます。r の付いた tag ができる前に clone したリポジトリでは、git fetch で新しい tag も取れます。次の例は第 2 章の rest-02-r2 に切り替えます。
git switch --detach rest-02-r2
--detach は、branch ではなく tag の指す commit をそのまま取り出す指定です。そこから手を加えるときは、git switch -c <branch の名前> で branch を作ってください。
この章の時点 (rest-01-r2) のリポジトリにあるのは、記事の例を確かめるテストだけです。
rest-api-order/
├── package.json # 使う道具と、その版
├── package-lock.json
├── .nvmrc # Node.js の版 (26)
├── tsconfig.json
├── vitest.config.ts
├── test/
│ ├── snippets/ # 記事の curl・コマンドと、その結果
│ ├── snippets.test.ts
│ ├── support/ # 実行と比較の処理
│ ├── harness.test.ts # 実行と比較の処理のテスト
│ └── fixtures/ # 上のテストに使う試しのファイル
└── .github/workflows/ci.yml
テストを動かす
npm run verify は、TypeScript の型の検査とテストを順に動かします。
npm run verify
Test Files 2 passed (2)
Tests 22 passed (22)
passed だけが並べば、手元の環境は整っています。
記事の例は動かして確かめている
このガイドに載せる curl とその応答、コマンドとその出力は、サンプルリポジトリのテストで実際に動かし、記事に載せたものと一致することを確かめています。
test/snippets/ には、記事の curl とコマンドと同じ中身のファイルと、その結果のファイルが、章の tag ごとに置いてあります。テストはそれを記事の順に 1 つずつ実行し、出力を結果のファイルと比べます。サーバーを使う例は、章ごとに記事と同じポートでサーバーを 1 回起動し、記事の順に送ります。読者が章の初めにサーバーを起動して、記事の順に打つのと同じ形です。上の node --version と curl --version も、テストが実行しています。
実行のたびに変わる値 (日時など) は、決まった値に置き換えてから比べます。記事にも置き換えた後の値を載せるので、手元で打つと、その部分だけが記事と違います。どの値を置き換えるかは、置き換える値が初めて出てくる次の章で示します。
章の構成
本文の後に、どの章も次の 4 つを置きます。
- 実務で効く注意点: その章で扱ったことを実務で使うときに、つまずきやすい点
- まとめ: 章の要点
- 次に読む: 前後の章と、詳しく扱うほかのガイド
- 練習問題: 設計の判断を問う 2 問。解答例は折りたたんであるので、考えてから開いてください
2 周目からの章は、冒頭に「要件の差分」の節を置き、前の周回から要件の何が変わったかを示します。
実務で効く注意点
仕様を先に書いても、照合しなければずれる
design-first で仕様を書いても、実装の途中でフィールドの名前を変えたり、エラーのときのステータスコードを変えたりすると、仕様と実装がずれます。仕様がずれると、仕様を読んでアプリを作った側が、本番で初めて食い違いに気づくことになります。
ずれを防ぐには、実装の応答を仕様と突き合わせるテストが要ります。このガイドでは、最初の周回の実装の部で、そのテストを CI に入れます。
Node.js の版をリポジトリに書いておく
Node.js の版が違うと、同じコードとテストでも結果が変わることがあります。サンプルリポジトリは、使う版を .nvmrc と package.json の engines に書き、CI も .nvmrc の版で動かしています。版をリポジトリに書いておくと、手元と CI と同僚の環境の版がそろい、「自分の手元では通る」の原因を 1 つ減らせます。
まとめ
- このガイドは、EC サイトの注文 API を、注文の作成と取得から始めて周回ごとに機能を足しながら作ります
- API は、別々に作られたプログラムどうしの取り決めです。公開した取り決めは変えにくいので、設計に時間をかけます
- 進め方は design-first です。要件 → ドメインモデル → リソース・表現・エラーの設計 → OpenAPI の仕様 → lint → モック → 実装 → 仕様との照合、を 1 周とします
- 第 1 部は言語に依存しない設計の部です。他の言語で実装する人も、第 1 部の仕様から自分の言語で実装できます
- 開発環境は Node.js 26・curl・Git・エディタです。サンプルリポジトリは章ごとの tag (
rest-NN。公開の後に直したときはrest-NN-r2など) を持ちます - 記事の curl とコマンドの例は、サンプルリポジトリのテストで実行して確かめています
次に読む
次章 HTTP の仕組み では、Web API が使う通信の仕組みを、curl でリクエストとレスポンスを見ながら確かめます。
練習問題
design-first で仕様を先に書くと、API を呼ぶアプリを作るチームは何を先に始められますか。逆に、仕様を先に書くことで生じる手間は何ですか
解答例
アプリを作るチームは、サーバーの実装ができるのを待たずに、仕様から作ったモックを相手に画面と通信の処理を作り始められます。仕様には、送るリクエストの形と返ってくる応答の形 (失敗したときの形も含む) が書いてあるので、エラーの表示も先に作れます。
手間は、実装の前に仕様を書く時間がかかることと、仕様と実装のずれを防ぐ照合が要ることです。仕様を書いた後に実装で決め直したことは、仕様にも戻して書き直す必要があります。このガイドでは、ずれを機械で見つけるために、実装の応答を仕様と突き合わせるテストを入れます。
最初の周回にログイン (認証) を入れず、注文の作成と取得だけにしたのはなぜですか。この判断で、注意しておくことは何ですか
解答例
1 つの機能で要件から実装までの全段を一度通し、各段で何を決めたかを見通しやすくするためです。認証を最初から入れると、トークンの検証や、会員ごとに見せる注文を絞る処理が全段に入り、注文の作成と取得という主題の判断が見えにくくなります。
注意しておくことは、認証の無い間は、注文の ID を知っていれば誰でもその注文を読めることです。最初の周回の API は、この状態で公開する前提ではありません。認証と、自分の注文だけを扱わせる認可は、第 5 部で入れます。後から入れるときに URL やエラーの形を作り直さずに済むよう、第 1 部の設計でも、認証が入った後の姿を考えながら決めます。