メインコンテンツまでスキップ

「rest-api」タグのついた14記事

全てのタグを見る

HTTP の仕組み: リクエストとレスポンスを curl で見る

REST API 設計・実装ガイドの第2章。Web API が使う HTTP の仕組みを、受け取ったリクエストをそのまま返すエコーサーバーに curl で送って観察します。URL の部分、リクエストとレスポンスの形、curl の使い方、よく使うヘッダ、JSON とメディアタイプ、ステートレス、HTTP のバージョンと HTTPS を扱います。

OpenAPI: 3.1 で仕様を書いて Swagger UI で読む

REST API 設計・実装ガイドの第11章。08〜10 章で決めたエンドポイント・表現・誤りの応答を、OpenAPI 3.1 の仕様に書きます。文書の構造、操作と operationId、パラメータとリクエストの本文、JSON Schema 2020-12 のスキーマ、$ref と components、例と問題の詳細の書き方を、選んだ理由と一緒に示します。仕様が設計の文書と食い違わないことをテストで確かめ、書いた仕様を Swagger UI で読みます。

REST API 設計・実装ガイド

REST API の設計と実装を、EC サイトの注文 API を題材に、要件の整理から OpenAPI の仕様・モック・TypeScript の実装・PostgreSQL・運用まで通して学ぶ全 50 章のガイド。Swagger UI・Redocly CLI・Prism・Bruno などの道具の使い方も扱います。対象は OpenAPI 3.1・Node.js 26・TypeScript 6.0 です。

REST の考え方: リソースと統一インターフェース

REST API 設計・実装ガイドの第7章。商品のサーバーに RPC 風の口を足し、リソースの URL と呼び比べて、2 つの形で意味がどこに書かれるかを確かめます。Fielding の論文の REST の制約と統一インターフェースの 4 つ、Richardson 成熟度モデル、HTTP を使うプロトコルの仕様の書き方を定めた RFC 9205 と、URI の設計と持ち主を扱う RFC 8820 を、このガイドの設計とつなげて読みます。

エラーの設計: ステータスコードと Problem Details

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 で置き、要件の文書に使わない語が無いことをテストで確かめます。

はじめに: design-first で注文 API を作る

REST API 設計・実装ガイドの第1章。このガイドで作る EC サイトの注文 API と最初の周回の範囲、仕様を先に書く design-first の進め方、章の種類ごとの読み方を示し、Node.js 26・curl・サンプルリポジトリを用意します。

メソッドとステータスコード: 操作の意味と結果の伝え方

REST API 設計・実装ガイドの第3章。HTTP のメソッドの意味、安全と冪等、ステータスコードの 5 分類とよく使うコード、Location と Allow、HEAD と OPTIONS を、手書きの商品のサーバーを curl で呼んで確かめます。章の終わりで、何を受け付けて何を返すかがコードの中にしか無いことを確かめ、仕様を先に書く理由を示します。

モック: Prism で動かして curl と Bruno で呼ぶ

REST API 設計・実装ガイドの第13章。束ねた OpenAPI の仕様から Prism でモックを動かし、curl で呼びます。Prefer ヘッダで応答を選ぶ方法、Prism のリクエストの検証と誤りの応答がエラーの設計の章の決まりとどう違うか、値を作る形のモックを示します。受け入れ条件を Bruno のリクエストにしてモックで確かめ、モックで確かめられない受け入れ条件を表にします。Swagger UI の Try it out からモックを呼ぶための CORS と、Postman との比べ方も扱います。

リソースの設計: 集約とコマンドから URL とメソッドを決める

REST API 設計・実装ガイドの第8章。ドメインモデルの集約・コマンド・リードモデルから注文の API のリソースを見つけ、URL の名前を決め、注文するコマンドを POST に写します。注文明細と商品を表現にどう含めるかを決め、Google の AIP・Zalando・Azure の指針と比べた理由を残します。ユースケースから操作の名前までの対応表を YAML で置き、文書と食い違わないことをテストで確かめます。

仕様の lint: Redocly CLI で検査して分割する

REST API 設計・実装ガイドの第12章。11 章で書いた OpenAPI の仕様を Redocly CLI で検査します。組み込みの規則集の選び方、指摘への応じ方、08〜10 章の決まりを自前の規則にする書き方、規則が働くことをテストで確かめる形、規約ごとに守り方を書くガイドラインを示します。仕様をファイルに分けて束ね、Redoc の文書を作り、検査を npm run verify と CI に足します。

表現の設計: JSON の形とメディアタイプ

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 周目に入れないものを決め、受け入れ条件を具体的な値にしてテストの名前に写します。