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

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

前の 3 つの章で、注文の API の要件とドメインモデルを決めました。次の章からは、そのモデルを API として見せる形、つまり URL とメソッドとステータスコードを決めます。その前に、この章で、このガイドがどんな形の API を作るのかと、その形が REST とどう関わるのかを確かめます。

前の章までの振り返り​

HTTP の仕組みとメソッドとステータスコードで見たことのうち、この章で使うものを挙げます。

  • メッセージは、開始行・ヘッダ・空行・本文からなります。リクエストの開始行にメソッドと対象が、レスポンスの開始行にステータスコードが入ります
  • メソッドの意味は、どのリソースに使っても同じです。GET・HEAD・OPTIONS は安全なメソッドで、安全なメソッドと PUT・DELETE は冪等です
  • ステータスコードは 1 桁目で 5 つに分類されます。作成は 201 と Location、使えないメソッドは 405 と Allow で知らせます
  • HTTP はステートレスです。各リクエストの意味は、それ単体で理解でき、同じ接続で前に送ったリクエストに左右されません

どれも HTTP の仕様が決めている意味です。この章では、この意味を API の設計にどこまで使うかで、API の形が分かれることを見ます。

API の形: RPC 風とリソース風​

この章では、HTTP で作る API の形を 2 つに分けて比べます。

  • RPC 風: 呼び出す操作を中心にした形です。RPC は Remote Procedure Call (遠隔手続き呼び出し) の略です。この章では、「商品を取り出す」「商品を作る」のような操作に名前を付け、操作の名前と引数を本文で 1 つの URL に送り、結果も失敗も本文で返す形を RPC 風と呼びます
  • リソース風: 操作の対象を中心にした形です。商品の一覧や商品 1 件のような対象 (リソース) ごとに URL を付け、何をするかをメソッドで、どうなったかをステータスコードで表します

この章の RPC 風は、この章の後半で読む Fowler の記事が、レベル 0 の例として挙げる形に当たります。操作の名前を URL に入れる形や、REST とは別の方式 (GraphQL・gRPC) は、この 2 つのどちらかにそのまま入るとは限りません。作った注文の状態を移す操作 (取り消しなど) の URL の決め方は第 4 部で、REST とは別の方式は第 8 部で比べます。注文を作る操作の URL とメソッドは、次の章で決めます。

3 章の商品のサーバーは、リソース風の形でした。rest-07-r2 のサーバーには、同じ商品を扱う RPC 風の口 /rpc を足しました。/rpc は比べるために作った口で、実際に使われている特定の RPC の方式を写したものではありません。

2 つの形を呼び比べる​

rest-07-r2 で、商品のサーバーを起動します。3 章で起動したサーバーが動いているなら、止めてから起動し直します。このサーバーは商品をメモリに持ち、起動するたびに 2 件 (りんごとみかん) から始まります。

node tools/product-server/server.ts
結果
商品のサーバーを http://localhost:3902 で起動しました

/rpc が操作を受け付けるのは POST だけです (OPTIONS には、使えるメソッドを返します)。本文の call で呼び出す操作を、ほかのキーで引数を指定します。用意した操作は、商品を取り出す getProduct と、商品を作る createProduct の 2 つです。コードは章末の「この章のサーバーのコード」にあります。

商品を取り出す​

RPC 風の口で、商品 p-1 を取り出します。

curl -s http://localhost:3902/rpc \
-H 'Content-Type: application/json' \
-d '{"call":"getProduct","id":"p-1"}'
結果
{
"result": {
"id": "p-1",
"name": "りんご"
}
}

リソース風では、商品 p-1 の URL に GET を送ります。

curl -s http://localhost:3902/products/p-1
結果
{
"id": "p-1",
"name": "りんご"
}

返る商品は同じです。違うのは、何をどうするかの書き方です。RPC 風では、取り出す商品 (id) も、取り出すという操作 (getProduct) も本文の中にあり、HTTP から見えるのは「/rpc への POST」だけです。リソース風では、取り出す商品は URL に、取り出すという操作はメソッド (GET) に表れています。

無い商品を取り出す​

無い商品 p-none を、-w でステータスコードも見ながら取り出します。まず RPC 風の口です。

curl -s -w '%{http_code}\n' http://localhost:3902/rpc \
-H 'Content-Type: application/json' \
-d '{"call":"getProduct","id":"p-none"}'
結果
{
"error": {
"message": "商品 p-none は見つかりません"
}
}
200

次にリソース風です。

curl -s -w '%{http_code}\n' http://localhost:3902/products/p-none
結果
{
"message": "商品 p-none は見つかりません"
}
404

RPC 風の口は、見つからなくても 200 を返し、失敗を本文の error で伝えます。リソース風は 404 です。ステータスコードだけを見るもの (アクセスログからステータスコードごとの件数を数える集計など) には、RPC 風の失敗は成功と見分けがつきません。

商品を作る​

RPC 風の口で、商品を作ります。-i でヘッダも見ます。

curl -s -i http://localhost:3902/rpc \
-H 'Content-Type: application/json' \
-d '{"call":"createProduct","name":"ぶどう"}'
結果
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 63
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{
"result": {
"id": "p-3",
"name": "ぶどう"
}
}

リソース風では、商品の一覧に POST します。

curl -s -i http://localhost:3902/products \
-H 'Content-Type: application/json' \
-d '{"name":"メロン"}'
結果
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 41
Location: /products/p-4
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{
"id": "p-4",
"name": "メロン"
}

RPC 風の作成は 200 で、作った商品を本文で返します。リソース風は 201 と Location で、新しい商品の URL を伝えます。RPC 風の口には、商品ごとの URL がありません。作った商品をもう一度取り出すには、getProduct に id を渡して呼びます。

意味がどこに書かれているか​

3 つの組を、意味がどこに書かれているかで並べます。

意味RPC 風 (/rpc)リソース風 (/products)
何を対象にするか本文の idURL (/products/p-1)
何をするか本文の callメソッド (GET・POST)
どうなったか本文の result と errorステータスコード (200・201・404) と本文

RPC 風の口で操作を呼ぶリクエストと、その応答では、メソッドとステータスコードはいつも POST と 200 で、意味はすべて本文にあります。本文の読み方を知っているのは、このサーバーに合わせて書いたクライアントだけです。リソース風では、意味の一部をメソッドとステータスコードに載せるので、HTTP を知っているものなら、このサーバーを知らなくても「取り出した」「無かった」「作った」を読めます。

この違いが何をもたらすかを、REST の考え方から確かめます。

Fielding の論文と REST の制約​

REST (Representational State Transfer) は、Roy Fielding が博士論文で示したアーキテクチャスタイルです。論文の題は "Architectural Styles and the Design of Network-based Software Architectures" で、2000 年にカリフォルニア大学アーバイン校に提出されました (論文)。論文の 5 章は、REST を分散ハイパーメディアシステムのためのスタイルとして導入しています (5 章)。

Fielding は、制約を持たない状態から出発し、システムの要素に制約を 1 つずつ加える方法で REST を導いています。REST は、それぞれの制約がもたらす性質を理由に選ばれた、制約の集まりです。

制約求めることもたらすものと代償
クライアントとサーバー (Client-Server)ユーザーインターフェースの関心と、データを保存する関心を分けるユーザーインターフェースを別の環境へ移しやすくなり、サーバーを単純にしてスケーラビリティが上がる。両者が独立に進化できる
ステートレス (Stateless)各リクエストが、理解に要る情報をすべて含み、サーバーに保存した文脈を使わない。セッションの状態はクライアントに置く可視性・信頼性・スケーラビリティ。代償は、同じデータを毎回送ることで、ネットワークの性能が下がりうること。論文はもう 1 つ、アプリケーションの状態をクライアントに置くので、振る舞いを一貫させるサーバーの制御が弱まることも挙げている
キャッシュ (Cache)応答のデータに、キャッシュしてよいかどうかを示すやり取りの一部を省けて、効率と体感の性能が上がる。代償は、キャッシュの古いデータで信頼性が下がりうること
統一インターフェース (Uniform Interface)部品の間のインターフェースを統一する (次の節の 4 つ)実装が、提供するサービスから切り離され、独立に進化できる。代償は、アプリケーションに合わせた形でなく標準の形で送るので、効率が下がること
階層化システム (Layered System)各部品が、直接やり取りする隣の層より先を見られないようにするシステム全体の複雑さに上限を設けられる。組織の境界の層で、境界を越えるデータにセキュリティのポリシーを当てられる。代償は処理のオーバーヘッドと遅延で、途中の共有キャッシュの利点で相殺できる
コードオンデマンド (Code-On-Demand)クライアントが、スクリプトなどのコードをダウンロードして実行できるクライアントを単純にできる。可視性を下げるので、REST の中では任意の制約

HTTP の仕組みで見たステートレスは、2 つ目の制約に当たります。HTTP の仕様が求めるのは、各リクエストの意味がそれ単体で理解できることです。REST はさらに、サーバーに保存した文脈を使わないことを、API の設計に求めます。注文の API では、ある注文を扱うのに要る情報 (注文 ID など) を、リクエストごとに URL や本文で送ります。前のリクエストで選んだ注文をサーバーが覚えておき、次のリクエストでそれを使う形にはしません。

Fielding は論文の 5 章のまとめで、REST の制約は全体として当てはめたときに、部品の間のやり取りのスケーラビリティ、インターフェースの汎用性、部品を独立にデプロイできること、中間の部品 (遅延を減らす・セキュリティを強制する・古いシステムを包む) を重んじる、と書いています。

統一インターフェースの 4 つ​

Fielding は、REST をほかのネットワーク型のスタイルと分ける中心の特徴は、部品の間の統一インターフェースを重んじることだとしています。そして、統一インターフェースを 4 つの制約で定義しています。

リソースの識別​

REST の情報の中心となる抽象は、リソースです。名前を付けられる情報は何でもリソースになりえます。文書や画像、「今日のロサンゼルスの天気」のような時間で変わるもの、ほかのリソースの集まり、人のような物理的な対象も含みます。リソースは、リソース識別子で識別します。今の Web では、URL がその識別子です。

Fielding は、リソースは実体の集合への概念上の対応付けで、ある時点でそれに当たる実体そのものではない、としています。変わってはならないのは、対応付けの意味だけです。商品 p-1 の名前が後で変わっても、/products/p-1 が「商品 p-1」を指すことは変わりません。識別子を割り当てた側が、この意味を保つ責任を負います。

商品のサーバーでは、/products が商品の一覧 (ほかのリソースの集まり) を、/products/p-1 が商品 p-1 を識別します。RPC 風の口は、どの操作も /rpc という 1 つの URL に送るので、URL からは対象を識別できません。

表現を通じたリソースの操作​

REST の部品は、リソースの今の状態か意図する状態を、表現として捉えます。そして、その表現を部品の間で送ることで、リソースを操作します。表現は、バイト列と、それを説明するメタデータからなります。

GET /products/p-1 の応答の JSON は、商品 p-1 の今の状態の表現です。POST /products で送った {"name":"メロン"} は、作ってほしい商品の状態の表現です。クライアントが受け取り、送るのは表現で、サーバーの中で商品をどう持っているか (このサーバーなら配列の要素) ではありません。表現を説明するメタデータの 1 つが、2 章で見たメディアタイプ (Content-Type) です。

自己記述的なメッセージ​

論文の 5 章は、この制約に専用の節を設けていません。5 章で働きをいちばん詳しく述べているのは、処理の見方を扱う節です。Fielding はそこで、REST はメッセージを自己記述的に制約することで、途中の部品による処理を可能にすると書いています。その中身として、リクエストの間のやり取りがステートレスであること、意味を示し情報をやり取りするのに標準のメソッドとメディアタイプを使うこと、応答がキャッシュしてよいかを明示することを挙げています (5.3.1)。階層化システムの節でも、メッセージが自己記述的で途中の部品にもその意味が見えるので、途中の部品がメッセージの内容を変換できると書いています。論文の 6 章には、REST を HTTP に当てはめた節の中に、自己記述的なメッセージの小節 (6.3.2) があります (6 章)。

表現を扱う節では、制御データが、求める動作や応答の意味のような、メッセージの目的を定めるとしています。受け手は、メッセージの制御データと、表現のメディアタイプに従って表現を処理します。このガイドでは、HTTP のメッセージで求める動作を表すのはメソッド、応答の意味を表すのはステータスコードだと読みます。

RPC 風の口では、操作と結果の意味が本文の call・result・error にあります。これらのキーの意味はこのサーバーだけの約束で、HTTP を知っているだけの部品には読めません。

アプリケーション状態のエンジンとしてのハイパーメディア​

4 つ目は、英語の頭文字から HATEOAS とも呼ばれます。この制約の名前は 5 章の制約の一覧に出るだけで、エンジンと状態の遷移を説明しているのは、データの見方を扱う節です。Fielding は、アプリケーションの状態 (クライアントが、いまどの段階にいるか) はユーザーエージェントが持つとしています。そして、アプリケーションは、手元の表現の中にある状態の遷移の選択肢を調べて選び、次の状態へ進むエンジンだと説明しています。これはハイパーメディアのブラウザの画面とちょうど合いますが、すべてのアプリケーションがブラウザだとは仮定していない、とも書いています。

ブラウザでは、ページの中のリンクとフォームが、次にできることを表します。人は、行き先の URL を前もって知らなくても、リンクをたどって進めます。API なら、応答の中に、次にできる操作と、その操作の URL を入れる形です。

商品のサーバーの応答で、これに近いのは 201 の Location だけです。作った商品の URL をサーバーが教えるので、クライアントは URL を組み立てずにたどれます。

Richardson 成熟度モデル​

Richardson 成熟度モデルは、Leonard Richardson が作ったモデルで、REST のやり方の主な要素を、リソース・HTTP の動詞・ハイパーメディア制御の 3 段に分けます。Martin Fowler が 2010 年の記事で紹介しています (Richardson Maturity Model)。レベルは 0 から 3 までです。

レベル内容この章のサーバー
0HTTP を遠隔のやり取りの運び役として使うだけで、Web の仕組みは使わない。1 つのエンドポイントに POST し、失敗も応答の本文で返す/rpc
1 (リソース)1 つのエンドポイントにすべてを送るのをやめ、個々のリソースとやり取りする。メソッドは、まだ POST (または GET) をトンネルとして使うだけなし
2 (HTTP の動詞)HTTP の動詞を、HTTP での使われ方にできるだけ近く使う。失敗には 200 と本文のエラーでなく、2xx 以外を返す/products
3 (ハイパーメディア制御)次に何ができるかと、そのために操作するリソースの URI を、応答の中で伝えるなし

Fowler の記事は、各レベルを一般的な設計の技法に対応させる見方を、Ian Robinson が強調した点として紹介しています。レベル 1 は分割統治 (大きなエンドポイントを複数のリソースに分ける)、レベル 2 は標準の動詞で似た場面を同じに扱うこと、レベル 3 は発見しやすさ (プロトコルを自己文書化しやすくする) です。

このモデルには、Fowler 自身が付けた断りがあります。このモデルは REST の要素を考えるよい方法だが、REST そのものの段階を定義したものではない、と強調しています。Roy Fielding はレベル 3 を REST の前提条件だと明言している、とも書いています。Fowler はこのモデルを、REST 的な考え方の基本を段階を追って理解するための学習の道具とみなし、何かを評価する仕組みに使うものではないとしています。

このガイドの API とハイパーメディア​

このガイドの注文の API は、リソースを URL で識別し、メソッドとステータスコードを HTTP の意味どおりに使う形 (レベル 2) で作ります。これはこのガイドの判断です。なお Fowler は同じ記事で、Web の存在が裏付けている要素として、安全な操作 (GET など) と安全でない操作をはっきり分けることと、ステータスコードを使って失敗の種類を伝えやすくすることを挙げています。

リンクは、使う場面を選んで入れます。注文を作ったときは、Location で注文の URL を返します。応答の中で商品をどう指すか (中に入れるか、ID とリンクで指すか) は、次の章で決めます。一覧の続きを指すリンクと、注文の状態に応じて次にできる操作を指すリンクは、第 4 部で、それを使う場面と一緒に扱います。

クライアントが応答の中のリンクだけをたどって操作を選ぶ形は、API の全体には求めません。利用者が、この部の後半で書く仕様 (OpenAPI) を読んで URL とメソッドを知り、それをクライアントに書き込みます。そのため、このガイドの API は、Fielding の意味での REST の制約をすべて満たすものではありません。

このガイドの書名の REST API は、この章でリソース風と呼んだ形の HTTP API を指します。Fielding の意味の REST より広く、この章の /rpc の形は入りません。REST API の語が Fielding の意味に限らずに使われる例として、RFC 9205 (次の節) は、Web の閲覧のほかに HTTP を土台に使うことが "HTTP-based APIs"・"REST APIs"・"HTTP APIs" と呼ばれることがあると書いています。第 8 部で扱う「REST の外側」は、GraphQL・gRPC のような、REST とは別の方式のことです。

RFC 9205 と RFC 8820: HTTP を使う仕様と URI の持ち主​

RFC 9205 "Building Protocols with HTTP" は、2022 年 6 月の Best Current Practice (BCP 56) です (RFC 9205)。HTTP を使って新しいアプリケーションのプロトコルを定める仕様の書き方について、ベストプラクティスを定めています。主に IETF の仕様のために書かれたものですが、ほかの場面にも当てはまりうる、としています。注文の API の設計に関わる点を挙げます。

  • 汎用の意味を定め直さない: HTTP の価値の多くは、どのリソースにも当てはまりうる汎用の意味にある。アプリケーション固有の意味は、ステータスコードやメソッドでなく、本文とヘッダで表すのがよい (ステータスコードとメソッドにも、アプリケーションの状態に関わる汎用の意味はある)。HTTP を使うアプリケーションは、メソッド・ステータスコード・既存のヘッダのような汎用の要素の意味の、定め直し・細分・上書きをしてはならない (MUST NOT)。使うメソッドとステータスコードは、登録済みのものだけにする (MUST)
  • GET の利点を手放さない: GET の取得の意味が、キャッシュと、副作用の無いリンクを可能にする。問い合わせを POST の本文で送ると、URL の長さの制限などは避けられるが、キャッシュや、問い合わせの結果へのリンクのような GET の利点を失う。両方のメソッドを受け付けることも検討するとよい
  • ステータスコードは汎用の部品も作る: ステータスコードは、アプリケーション以外の部品も作ることが多い。アプリケーションがステータスコードに固有の意味を割り当てると、汎用の部品が作ったコードを見て、クライアントが状態を誤解しうる。失敗には最も当てはまるコードを使い、迷ったら一般的な 3 つのコード (200・400・500) を多めに使う。ステータスコードとアプリケーションのエラーを 1 対 1 に対応させない。同じコードに当たる失敗を区別するには、本文やヘッダで細かい情報を伝える
  • URL の空間を占拠しない: 標準がサーバーの URL の空間の一部をアプリケーションのものと決めてかかると、サーバーが自分のリソースに持つ権限を奪うので、標準では悪い慣行とする。パスのような URI の部品を固定で定めるより、リンクを定めて使うことを推奨する (RECOMMENDED)

1 つ目と RPC 風の口の関係は、取り違えやすいところです。RFC 9205 も、アプリケーション固有の意味は本文とヘッダで表すよう勧めています。ただし、ステータスコードとメソッドにも汎用の意味があると断ったうえでの話です。「対象が見つからない」には 404 という最も当てはまるコードがあり、RPC 風の口は、それを本文の error にしか書いていません。本文で伝える細かい情報の形は、エラーの設計の章で決めます。

RFC 8820 "URI Design and Ownership" は、2020 年 6 月の Best Current Practice (BCP 190) で、RFC 9205 が URL の空間の扱いで引いている文書です (RFC 8820)。URI の構造はスキームが定め、スキームはその下の構造を URI の持ち主に委ねることが多い、としています。持ち主でない者が特定の構造を義務づけると、衝突や硬直などの害が出うる、という立場です。仕様は、スキームの定義が許す場合を除き、/myapp のような URI のパスの固定の接頭辞を定めてはならない (MUST NOT) としています。ただし、サーバーが管理するリソースの「下」に、アプリケーションがパスの構造を定める場合は当てはまらない、とも書いています。

RFC 8820 の指針が対象にするのは、URI の構文や構造を制約する仕様を書く人です。注文の API の URL は、API を提供する側が、自分のサーバーの URL として決めます。RFC 9205 も、1 つの展開のための API の仕様でパスの接頭辞 (/app/v1 など) を定めるのはよくある慣行で、IETF の仕様でそうするのが不適切なのだ、と書いています。このガイドが URL を設計できるのは、この持ち主の立場にいるからです。

そのうえで、2 つの RFC は、URL を固定の構文として約束するより、プロトコルの中でやり取りするリンクとして使うことを勧めています。作った注文の URL を Location で返すのは、この考え方に沿った形です。

実務で効く注意点​

成熟度のレベルで API を採点しない​

「この API はレベル 2 だからレベル 3 に上げる」のように、Richardson 成熟度モデルを採点に使うと、Fowler が断った使い方になります。モデルは、各レベルが何をもたらすかを学ぶ道具です。リンクを入れるかどうかは、レベルの数でなく、クライアントがそのリンクで何を得るか (URL を組み立てずに済む、次にできる操作が分かる) で決めます。

取り出すだけの操作を POST にまとめない​

RPC 風の口の getProduct のように、取り出すだけの操作を POST で送ると、RFC 9205 の言う GET の利点 (キャッシュや、結果へのリンク) を失います。検索の条件が長くて URL に収まらないなど、POST を選ぶ理由があるときは、その利点と比べて決めます。RFC 9205 は、GET と POST の両方を受け付けることも検討するよう勧めています。

まとめ​

  • この章の RPC 風 (/rpc の形) は、操作の名前と引数を 1 つの URL に本文で送ります。リソース風は、対象を URL で、何をするかをメソッドで、どうなったかをステータスコードで表します
  • REST は、Fielding が論文で、制約を 1 つずつ加えて導いたアーキテクチャスタイルです。ステートレスは、その制約の 1 つです
  • 統一インターフェースは、リソースの識別・表現を通じたリソースの操作・自己記述的なメッセージ・アプリケーション状態のエンジンとしてのハイパーメディアの 4 つの制約で定義されます
  • Fowler は、Richardson 成熟度モデルを REST の要素を段階を追って学ぶ道具とみなし、REST そのものの段階の定義ではないとしています。RPC 風の口はレベル 0、商品の URL はレベル 2 に当たります
  • このガイドの書名の REST API は、リソース風の HTTP API を指します
  • このガイドの API はレベル 2 の形で作り、リンクは使う場面を選んで入れます
  • RFC 9205 は、HTTP の汎用の意味を定め直さないことを求めます。RFC 8820 は、URL の構造をサーバーの持ち主が決めるものとしています

次に読む​

前の章は ドメインモデル です。

次章 リソースの設計 では、前の章の集約と、注文するというコマンドから、注文の API のリソースと URL とメソッドを決めます。

練習問題​

/rpc の口を、Richardson 成熟度モデルのレベル 1 に変えるには、何を変えればよいでしょうか。レベル 2 との違いも考えてください

解答例

1 つの /rpc にすべてを送るのをやめ、商品ごとの URL (/products/p-1 など) に送るようにします。たとえば、/products/p-1 に {"call":"get"} を POST する形です。対象は URL で識別するようになりますが、何をするかは本文の call のままで、メソッドは POST をトンネルとして使うだけです。これがレベル 1 です。

レベル 2 では、何をするかもメソッドで表します。取り出すなら GET を送り、見つからなければ 404 を返します。3 章の /products が、この形です。

RPC 風の口は、見つからない商品にも 200 を返します。この口を呼ぶクライアントは、失敗をどこで見分ける必要があるでしょうか

解答例

本文の error と、ステータスコードの両方です。

本文の error は、商品が見つからないような、このサーバーが決めた失敗を表します。一方で、ステータスコードは、アプリケーション以外の部品も作ります。途中のプロキシやサーバーの前に置いた仕組みが、502 や 503 のような応答を返すことがあり、その本文には error がありません。RPC 風の口を呼ぶクライアントは、HTTP の層の失敗をステータスコードで、このサーバーの失敗を本文で、と 2 か所を見ることになります。

リソース風なら、どちらの失敗もまずステータスコードの分類で分けられ、細かい区別だけを本文で見ます。

この章のサーバーのコード​

商品のサーバーのコードです。3 章のコードに、/rpc の口 (callRpc) と、2 つの口で共有する関数 (receiveBody・fieldOf・addProduct) を足しました。読まなくても本文は追えます。

/*
* 商品を ID と名前だけで持つ、手書きのサーバー。3 章でメソッドとステータスコードを観察し、
* 7 章でリソースの URL と RPC 風の口 (/rpc) を呼び比べるのに使う。
* 設計した API ではない。何を受け付けて何を返すかは、このコードの中にしか書いていない。
*/
import { createServer } from 'node:http';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { text } from 'node:stream/consumers';

const port = 3902;

interface Product {
id: string;
name: string;
}

const products: Product[] = [
{ id: 'p-1', name: 'りんご' },
{ id: 'p-2', name: 'みかん' },
];
let nextNumber = 3;

/**
* 本文を JSON で返す。HEAD のリクエストには、Node.js が本文を送らずにヘッダだけを返す。
* Content-Length を書くのは、HEAD の応答にも GET と同じ長さを載せるため。書かないと Node.js は本文を chunked で送り、
* HEAD の応答に長さが出ない。
*/
function sendJson(res: ServerResponse, status: number, body: unknown, headers: Record<string, string> = {}): void {
const json = `${JSON.stringify(body, null, 2)}\n`;
res.writeHead(status, {
'Content-Type': 'application/json',
'Content-Length': String(Buffer.byteLength(json)),
...headers,
});
res.end(json);
}

function sendEmpty(res: ServerResponse, status: number, headers: Record<string, string>): void {
res.writeHead(status, headers);
res.end();
}

/** type と subtype は大文字小文字を区別しない (RFC 9110 の 8.3.1) ので、パラメータ (; charset=utf-8 など) を除いて小文字で比べる。 */
function isJson(contentType: string | undefined): boolean {
return contentType?.split(';')[0].trim().toLowerCase() === 'application/json';
}

/**
* 受け取る途中で接続が切れたときは、応答を返す相手がいないので、接続を閉じて undefined を返す。
* 捕まえないと、この async の関数の外で処理されないまま、サーバーのプロセスが止まる。
*/
async function receiveBody(req: IncomingMessage, res: ServerResponse): Promise<string | undefined> {
try {
return await text(req);
} catch {
res.destroy();
return undefined;
}
}

/** 本文の JSON は null や数のこともあり、それに in を使うと例外になるので、オブジェクトと確かめてから key を読む。 */
function fieldOf(value: unknown, key: string): unknown {
return typeof value === 'object' && value !== null && key in value ? (value as Record<string, unknown>)[key] : undefined;
}

function addProduct(name: string): Product {
const product = { id: `p-${nextNumber++}`, name };
products.push(product);
return product;
}

async function createProduct(req: IncomingMessage, res: ServerResponse): Promise<void> {
if (!isJson(req.headers['content-type'])) {
sendJson(res, 415, { message: '本文は application/json で送ってください' });
return;
}
const body = await receiveBody(req, res);
if (body === undefined) return;
let input: unknown;
try {
input = JSON.parse(body);
} catch {
sendJson(res, 400, { message: '本文が JSON として読めません' });
return;
}
const name = fieldOf(input, 'name');
if (typeof name !== 'string' || name === '') {
sendJson(res, 400, { message: 'name を文字列で指定してください' });
return;
}
const product = addProduct(name);
sendJson(res, 201, product, { Location: `/products/${product.id}` });
}

/**
* RPC 風の口。取得も作成も POST /rpc に送り、何をするかを本文の call で指定する。
* 結果も失敗も 200 で返し、本文の result と error のどちらがあるかで見分ける。
* /products の POST と違って Content-Type を見ず、本文を JSON として読めるかだけを見る。
*/
async function callRpc(req: IncomingMessage, res: ServerResponse): Promise<void> {
const body = await receiveBody(req, res);
if (body === undefined) return;
let input: unknown;
try {
input = JSON.parse(body);
} catch {
sendJson(res, 200, { error: { message: '本文が JSON として読めません' } });
return;
}
/*
* call と id には JSON のどの値も届く。文字列でない値を文に埋めると、{"toString":0} のようなオブジェクトでは
* 文字列に変える途中で例外が出て、この async の関数の外で処理されないまま、サーバーのプロセスが止まる。
*/
const call = fieldOf(input, 'call');
if (typeof call !== 'string') {
sendJson(res, 200, { error: { message: 'call を文字列で指定してください' } });
return;
}
if (call === 'getProduct') {
const id = fieldOf(input, 'id');
if (typeof id !== 'string') {
sendJson(res, 200, { error: { message: 'id を文字列で指定してください' } });
return;
}
const product = products.find((p) => p.id === id);
if (product === undefined) {
sendJson(res, 200, { error: { message: `商品 ${id} は見つかりません` } });
return;
}
sendJson(res, 200, { result: product });
return;
}
if (call === 'createProduct') {
const name = fieldOf(input, 'name');
if (typeof name !== 'string' || name === '') {
sendJson(res, 200, { error: { message: 'name を文字列で指定してください' } });
return;
}
sendJson(res, 200, { result: addProduct(name) });
return;
}
sendJson(res, 200, { error: { message: `${call} という呼び出しはありません` } });
}

createServer(async (req, res) => {
// http.Server が渡すリクエストには、method と url が必ずある (型が省略可なのは、クライアントが受ける応答と型を共用するため)。
const method = req.method!;
const target = req.url!;
/*
* リクエストの対象は、/ で始まるパス (origin-form) のほかに、http://… の絶対形式 (absolute-form) でも届き、
* サーバーは絶対形式も受け付ける (RFC 9112 の 3.2.2)。/ で始まる対象を基準の URL に対して解決すると、// で始まるパスを
* 別のホストと読むので、パスには localhost を前に付ける。
* *:99999 のように URL として読めないものも届く。new URL は読めないと例外を投げ、この async の関数の外で
* 処理されないまま、サーバーのプロセスが止まるので、読めなければ null を返す URL.parse を使う。
*/
const url = target.startsWith('/') ? URL.parse(`http://localhost${target}`) : URL.parse(target);
if (url === null) return sendJson(res, 400, { message: 'リクエストの対象を URL として読めません' });
const path = url.pathname;

if (path === '/products') {
const allow = 'GET, HEAD, POST, OPTIONS';
if (method === 'GET' || method === 'HEAD') return sendJson(res, 200, products);
if (method === 'POST') return createProduct(req, res);
if (method === 'OPTIONS') return sendEmpty(res, 204, { Allow: allow });
return sendJson(res, 405, { message: `${method} はこの URL で使えません` }, { Allow: allow });
}

if (path === '/rpc') {
const allow = 'POST, OPTIONS';
if (method === 'POST') return callRpc(req, res);
if (method === 'OPTIONS') return sendEmpty(res, 204, { Allow: allow });
return sendJson(res, 405, { message: `${method} はこの URL で使えません` }, { Allow: allow });
}

const match = /^\/products\/([^/]+)$/.exec(path);
if (match) {
const allow = 'GET, HEAD, OPTIONS';
if (method === 'OPTIONS') return sendEmpty(res, 204, { Allow: allow });
if (method !== 'GET' && method !== 'HEAD') {
return sendJson(res, 405, { message: `${method} はこの URL で使えません` }, { Allow: allow });
}
const product = products.find((p) => p.id === match[1]);
if (product === undefined) return sendJson(res, 404, { message: `商品 ${match[1]} は見つかりません` });
return sendJson(res, 200, product);
}

sendJson(res, 404, { message: `${path} は見つかりません` });
}).listen(port, () => {
console.log(`商品のサーバーを http://localhost:${port} で起動しました`);
});