HTTP の仕組み: リクエストとレスポンスを curl で見る
REST API 設計・実装ガイドの第2章。Web API が使う HTTP の仕組みを、受け取ったリクエストをそのまま返すエコーサーバーに curl で送って観察します。URL の部分、リクエストとレスポンスの形、curl の使い方、よく使うヘッダ、JSON とメディアタイプ、ステートレス、HTTP のバージョンと HTTPS を扱います。
REST API 設計・実装ガイドの第2章。Web API が使う HTTP の仕組みを、受け取ったリクエストをそのまま返すエコーサーバーに curl で送って観察します。URL の部分、リクエストとレスポンスの形、curl の使い方、よく使うヘッダ、JSON とメディアタイプ、ステートレス、HTTP のバージョンと HTTPS を扱います。
REST API 設計・実装ガイドの第11章。08〜10 章で決めたエンドポイント・表現・誤りの応答を、OpenAPI 3.1 の仕様に書きます。文書の構造、操作と operationId、パラメータとリクエストの本文、JSON Schema 2020-12 のスキーマ、$ref と components、例と問題の詳細の書き方を、選んだ理由と一緒に示します。仕様が設計の文書と食い違わないことをテストで確かめ、書いた仕様を Swagger UI で読みます。
REST API の設計と実装を、EC サイトの注文 API を題材に、要件の整理から OpenAPI の仕様・モック・TypeScript の実装・PostgreSQL・運用まで通して学ぶ全 50 章のガイド。Swagger UI・Redocly CLI・Prism・Bruno などの道具の使い方も扱います。対象は OpenAPI 3.1・Node.js 26・TypeScript 6.0 です。
REST API 設計・実装ガイドの第7章。商品のサーバーに RPC 風の口を足し、リソースの URL と呼び比べて、2 つの形で意味がどこに書かれるかを確かめます。Fielding の論文の REST の制約と統一インターフェースの 4 つ、Richardson 成熟度モデル、HTTP を使うプロトコルの仕様の書き方を定めた RFC 9205 と、URI の設計と持ち主を扱う RFC 8820 を、このガイドの設計とつなげて読みます。
REST API 設計・実装ガイドの第10章。注文の作成と取得で起きる失敗を並べ、ステータスコードと誤りの応答の形を決めます。入力の誤りに 400 と 422 のどちらを使うか、在庫不足に 409・422・400 のどれを使うかを、RFC と Zalando・Google の AIP・Azure の指針で比べて決めます。Problem Details (RFC 9457) で問題の型の表と例を作り、テストで確かめます。
REST API 設計・実装ガイドの第6章。前の章のボードと用語集から、エンティティと値オブジェクト、集約と不変条件を決めます。消費税額は、税率ごとに 1 回だけ端数を処理する国税庁の資料の考え方に合わせ、切り捨てを選んで計算例を JSON で残します。1 つのトランザクションで 1 つの集約インスタンスを変える原則と、1 周目に注文と在庫を一緒に変える例外、境界づけられたコンテキストとクラス図を扱います。
REST API 設計・実装ガイドの第5章。注文の 1 周目で起きる出来事を、イベントストーミングで時系列に並べます。付箋の種類、並べる手順、ホットスポットから要件へ戻る流れを扱い、付箋の語から用語集を作って YAML で置き、要件の文書に使わない語が無いことをテストで確かめます。
REST API 設計・実装ガイドの第1章。このガイドで作る EC サイトの注文 API と最初の周回の範囲、仕様を先に書く design-first の進め方、章の種類ごとの読み方を示し、Node.js 26・curl・サンプルリポジトリを用意します。
REST API 設計・実装ガイドの第3章。HTTP のメソッドの意味、安全と冪等、ステータスコードの 5 分類とよく使うコード、Location と Allow、HEAD と OPTIONS を、手書きの商品のサーバーを curl で呼んで確かめます。章の終わりで、何を受け付けて何を返すかがコードの中にしか無いことを確かめ、仕様を先に書く理由を示します。
REST API 設計・実装ガイドの第13章。束ねた OpenAPI の仕様から Prism でモックを動かし、curl で呼びます。Prefer ヘッダで応答を選ぶ方法、Prism のリクエストの検証と誤りの応答がエラーの設計の章の決まりとどう違うか、値を作る形のモックを示します。受け入れ条件を Bruno のリクエストにしてモックで確かめ、モックで確かめられない受け入れ条件を表にします。Swagger UI の Try it out からモックを呼ぶための CORS と、Postman との比べ方も扱います。
REST API 設計・実装ガイドの第8章。ドメインモデルの集約・コマンド・リードモデルから注文の API のリソースを見つけ、URL の名前を決め、注文するコマンドを POST に写します。注文明細と商品を表現にどう含めるかを決め、Google の AIP・Zalando・Azure の指針と比べた理由を残します。ユースケースから操作の名前までの対応表を YAML で置き、文書と食い違わないことをテストで確かめます。
REST API 設計・実装ガイドの第12章。11 章で書いた OpenAPI の仕様を Redocly CLI で検査します。組み込みの規則集の選び方、指摘への応じ方、08〜10 章の決まりを自前の規則にする書き方、規則が働くことをテストで確かめる形、規約ごとに守り方を書くガイドラインを示します。仕様をファイルに分けて束ね、Redoc の文書を作り、検査を npm run verify と CI に足します。
REST API 設計・実装ガイドの第9章。受け入れ条件の例から注文の JSON の形を決めます。キーの名前、ID・金額・日時・状態の表し方、null と省略、リクエストとレスポンスの形、Content-Type と Accept の扱いを、Google の AIP・Zalando・Azure の指針と RFC と比べて決め、例を JSON ファイルにしてテストで確かめます。
REST API 設計・実装ガイドの第4章。注文の API の 1 周目の要件を、ユーザーストーリーと受け入れ条件 (Given・When・Then)、ユースケース記述で書きます。INVEST、画面と API の受け持ち、機能でない要件、1 周目に入れないものを決め、受け入れ条件を具体的な値にしてテストの名前に写します。