メソッドとステータスコード: 操作の意味と結果の伝え方
前の章で、リクエストの開始行にはメソッドが、レスポンスの開始行にはステータスコードがあることを見ました。この章では、その 2 つが何を意味するかを扱います。メソッドはクライアントが何をしたいかを、ステータスコードはサーバーがそれをどう処理したかを伝えます。API を設計するときは、操作ごとにこの 2 つを選びます。
観察には、商品を 2 件だけ持つ手書きのサーバーを使います。設計した API ではなく、メソッドとステータスコードを見るための道具です。
利用者とクライアント
この章から、API に関わる人とプログラムを次の語で呼び分けます。
- 利用者: API を使ってアプリを作る開発者と、その組織
- クライアント: API を呼ぶプログラム (アプリや curl)
- 購入者: 注文する人
API の設計の判断は、利用者が読み、利用者がクライアントに書き込むものです。「エラーのときに何が返るか」を利用者が前もって知らなければ、クライアントは失敗をうまく扱えません。購入者は API を直接は見ず、利用者が作ったアプリを通して使います。
商品のサーバーを起動する
rest-03-r2 で、商品のサーバーを起動します。
node tools/product-server/server.ts
商品のサーバーを http://localhost:3902 で起動しました
このサーバーは、/products (商品の一覧) と /products/<ID> (商品 1 件) の 2 種類の URL を持ちます。前の章のエコーサーバーとは別のポート (3902) で待ち受けます。コードは章末の「この章のサーバーのコード」にあります。
メソッドの意味
メソッドは、リクエストの意味を決める主な部分で、クライアントが何のためにリクエストし、成功したら何を期待しているかを表します。HTTP の仕様 (RFC 9110・RFC 5789) が定めるメソッドのうち、API で使うものを挙げます。
| メソッド | 意味 |
|---|---|
| GET | 対象のリソースの、今の表現を取り出す |
| HEAD | GET と同じだが、本文を返さずヘッダだけを返す |
| POST | 送った表現を、対象のリソースのやり方で処理させる。新しいリソースを作るのによく使う |
| PUT | 対象のリソースの状態を、送った表現で作るか置き換える |
| PATCH | 対象のリソースに、送った変更を部分的に当てる |
| DELETE | 対象のリソースを取り除く |
| OPTIONS | 対象のリソースで使える通信の選択肢 (使えるメソッドなど) を問い合わせる |
メソッドの名前は大文字と小文字を区別し、決まったメソッドはすべて大文字で書きます。1 つのメソッドの意味は、どのリソースに使っても同じです。GET はどの URL に送っても「取り出す」で、そのリソースが GET に応じるかどうかはリソースごとに決まります。
商品の一覧を GET で取り出します。
curl -s http://localhost:3902/products
[
{
"id": "p-1",
"name": "りんご"
},
{
"id": "p-2",
"name": "みかん"
}
]
1 件を取り出し、-w でステータスコードも見ます。
curl -s -w '%{http_code}\n' http://localhost:3902/products/p-1
{
"id": "p-1",
"name": "りんご"
}
200
POST と PUT は、どちらもリソースに表現を送りますが、意図が違います。PUT は「送った表現で、この URL のリソースの状態を置き換えてほしい」で、URL はクライアントが決めます。POST は「送った表現を、この URL のリソースのやり方で処理してほしい」で、処理の結果として新しいリソースができるなら、その URL はサーバーが決めます。HTTP の仕様は、新しいリソースの URL をサーバーが選ぶ場合は PUT でなく POST を使うよう求めています。
GET のリクエストには本文を付けません。HTTP の仕様は GET の本文に意味を定めておらず、本文でリクエストの意味を変えることはできません。
安全と冪等
メソッドには、安全と冪等という 2 つの性質があります。
- 安全: そのメソッドの意味が読み取り専用で、クライアントはサーバーの状態が変わることを求めていない
- 冪等: 同じリクエストを何回送っても、サーバーに対して意図した効果が 1 回送ったときと同じ
| メソッド | 安全 | 冪等 |
|---|---|---|
| GET・HEAD・OPTIONS | はい | はい |
| PUT・DELETE | いいえ | はい |
| POST・PATCH | いいえ | いいえ |
安全は「サーバーで何も起きない」という意味ではありません。GET を受けたサーバーがアクセスの記録を残すのは自由で、それでも GET は安全です。安全かどうかは、クライアントが状態の変化を求めたかどうかで決まります。
冪等も、意図した効果についての性質です。DELETE で商品を消したあと、同じ DELETE をもう一度送ると、2 回目のレスポンスは 404 になるかもしれません。それでも「その商品が無い」という効果は 1 回目と同じなので、DELETE は冪等です。
POST が冪等でないことを確かめます。curl に同じ URL を 2 つ渡すと、同じ POST を 2 回送ります。
curl -s http://localhost:3902/products http://localhost:3902/products \
-H 'Content-Type: application/json' \
-d '{"name":"ぶどう"}'
{
"id": "p-3",
"name": "ぶどう"
}
{
"id": "p-4",
"name": "ぶどう"
}
同じ中身を 2 回送ると、別の ID の商品が 2 つできました。
2 つの性質を区別するのは、HTTP の仕組みがそれを当てにして動くからです。
- 安全: 検索エンジンの巡回やブラウザの先読みは、安全なメソッドなら害が無いものとして、リンクを自動で辿ります。GET で状態を変える API は、巡回されただけでデータが変わります
- 冪等: 応答を受け取る前に通信が切れたとき、クライアントは冪等なリクエストなら自動で送り直せます。冪等でないリクエストは、送り直すと処理が 2 回行われるおそれがあるので、HTTP の仕様は、処理されなかったと分かる手段の無い限り自動で送り直さないよう求めています
このガイドの「注文する」は POST で作ります。通信が切れたときに注文が 2 つできないようにする工夫 (冪等性キー) は、第 4 部で扱います。
ステータスコード
ステータスコードは、リクエストの結果を表す 3 桁の数で、100 から 599 までです。1 桁目が結果の分類を表します。
| 分類 | 意味 |
|---|---|
| 1xx | 受け取って、処理を続けている |
| 2xx | 成功した |
| 3xx | 完了するには、クライアントにさらに操作が要る (リダイレクトなど) |
| 4xx | クライアントの側に誤りがある |
| 5xx | サーバーの側で処理できなかった |
クライアントは、すべてのステータスコードを知っている必要はありません。HTTP の仕様は、知らないコードを受け取ったら、その分類の x00 と同じに扱うよう求めています。知らない 471 を受け取ったクライアントは、400 として扱えます。
API でよく使うコードを挙げます。
| コード | 名前 | 使う場面 |
|---|---|---|
| 200 | OK | 成功した。本文はメソッドによる (GET なら取り出した表現) |
| 201 | Created | 成功し、新しいリソースを作った |
| 204 | No Content | 成功し、返す本文が無い |
| 400 | Bad Request | リクエストの形が誤っているなど、クライアントの誤りで処理できない |
| 401 | Unauthorized | 有効な認証の情報が無いので、処理しなかった |
| 403 | Forbidden | リクエストは理解したが、実行を断る |
| 404 | Not Found | 対象のリソースが見つからない |
| 405 | Method Not Allowed | そのメソッドは、このリソースでは使えない |
| 409 | Conflict | リソースの今の状態と衝突するので、完了できない |
| 422 | Unprocessable Content | 形式も構文も正しいが、中身の指示を処理できない |
| 500 | Internal Server Error | サーバーが予期しない状況で処理できなかった |
401 と 403 の違いは、認証の情報の有無です。401 は「誰なのかが分からない (分かる情報が無いか、無効)」、403 は「誰なのかは分かったうえで、その操作を断る」です。認証の仕組みは第 5 部で扱います。
無い商品を取り出すと、404 が返ります。
curl -s -w '%{http_code}\n' http://localhost:3902/products/p-none
{
"message": "商品 p-none は見つかりません"
}
404
本文が JSON として読めない POST には、400 が返ります。
curl -s -w '%{http_code}\n' http://localhost:3902/products \
-H 'Content-Type: application/json' \
-d '{"name":'
{
"message": "本文が JSON として読めません"
}
400
Content-Type を付け忘れた POST には、415 (Unsupported Media Type) が返ります。前の章で見たとおり、curl の -d はフォームの形式を名乗るので、このサーバーは本文の形式を受け付けません。
curl -s -w '%{http_code}\n' http://localhost:3902/products -d '{"name":"ぶどう"}'
{
"message": "本文は application/json で送ってください"
}
415
400 と 422 は、どちらも「クライアントが送ったものを処理できない」ですが、HTTP の仕様の定義が違います。400 は構文が誤っているなど、リクエストそのものを処理できない場合です。422 は、形式を理解でき構文も正しいが、中身の指示を処理できない場合です。このサーバーは name が無いときも 400 を返しますが、これを 422 にする設計もありえます。どちらにするかは、エラーの設計の章で決めます。
201 と Location
POST で新しいリソースを作ったときは、201 を返し、Location ヘッダで新しいリソースの URL を知らせます。HTTP の仕様は、POST で 1 つ以上のリソースを作ったら、作った主なリソースを指す Location を付けた 201 を返すよう求めています。
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-5
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{
"id": "p-5",
"name": "ぶどう"
}
「安全と冪等」の節で送った 2 回の POST で商品が 2 件増えているので、新しい商品の ID はその次の番号になります。結果の Location の値はホストを含まない相対の参照で、リクエストを送った URL を基準に読みます。クライアントは、この URL に GET を送れば、作った商品を取り出せます。
405 と Allow
リソースが受け付けないメソッドを送ると、405 が返ります。
curl -s -i -X POST http://localhost:3902/products/p-1
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 57
Allow: GET, HEAD, OPTIONS
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{
"message": "POST はこの URL で使えません"
}
405 には、そのリソースが受け付けるメソッドを並べた Allow ヘッダを付けます。HTTP の仕様では、これは任意でなく必須です。405 は「サーバーはそのメソッドを知っているが、このリソースでは使えない」で、サーバーがメソッドそのものを知らない (実装していない) ときは 501 (Not Implemented) を返します。
HEAD と OPTIONS
HEAD は、GET と同じヘッダを返し、本文を返しません。本文を受け取らずに、大きさ (Content-Length) や形式を確かめたいときに使います。curl では -I で送ります。
curl -s -I http://localhost:3902/products
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 253
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Content-Length は、いま GET を送ったら返る本文の長さです。ここまでの POST で商品が 3 件増えているので、章の初めの一覧より長くなっています。HEAD を送るときに -X HEAD と書かないのは、-X がリクエストの開始行のメソッドの語だけを変え、curl の動き (本文を待つかどうか) を変えないからです。このサーバーに curl -s -i -X HEAD http://localhost:3902/products と送ると、curl はヘッダを表示した後も Content-Length が示す長さの本文を待ち、すぐには終わりません。サーバーが使われていない接続を閉じたところで、本文を受け取りきれなかったという誤りで終わります (-s を付けているので、誤りの文は表示されません)。
OPTIONS は、そのリソースで使えるメソッドなどを問い合わせます。このサーバーは、204 と Allow で答えます。
curl -s -i -X OPTIONS http://localhost:3902/products
HTTP/1.1 204 No Content
Allow: GET, HEAD, POST, OPTIONS
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5
OPTIONS は、ブラウザが別のオリジンの API を呼ぶ前の確認 (CORS の preflight) にも使われます。CORS は、ブラウザの画面からモックを呼ぶときに モックの章で扱います。
Content-Type の比べ方
このサーバーは、本文の Content-Type から ; の後のパラメータを除いた部分 (type・subtype) を、大文字・小文字を区別せずに application/json と比べます。HTTP の仕様は、type・subtype の大文字・小文字を区別しないと定めています。HTTP の仕組みの章で見たとおり、application/json には charset のパラメータが定義されておらず、付けても効果がありません。charset=utf-8 を付けた POST でも、商品を作ります。
curl -s -i http://localhost:3902/products \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{"name":"もも"}'
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 38
Location: /products/p-6
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{
"id": "p-6",
"name": "もも"
}
何を受け付けて何を返すかは、どこに書いてあるか
この章で使ったサーバーについて、利用者の立場で次の問いに答えられるかを考えてみます。
/products/<ID>で使えるメソッドはどれか- 商品を作るとき、本文に何を書けばよいか。
nameのほかに何を送れるか - 失敗したとき、本文はどんな形で返るか。
messageのほかに何が入るか nameが空のとき、400 と 422 のどちらが返るか
答えは、どれもサーバーのコードの中にしか書いてありません。利用者がそれを知るには、コードを読むか、リクエストを送って試すしかありません。405 の Allow のように HTTP の仕組みで分かることもありますが、本文の形や失敗のときの形は分かりません。
コードを書いた人が「name が無ければ 400」と決めたのは、コードを書いているその場の判断です。同じチームの別の人が別の URL を書けば、同じ失敗に 422 を返すかもしれません。判断が散らばったまま公開すると、利用者は URL ごとに違う約束に合わせることになります。
このガイドが仕様を先に書くのは、この判断を、コードを書く前に 1 か所で行い、利用者が読める形で残すためです。次の章から、注文の API について、要件を書くところから始めます。
実務で効く注意点
GET で状態を変えない
GET /orders/123/cancel のように、GET で状態を変える URL を作ると、検索エンジンの巡回やブラウザの先読み、リンクの表示の確認 (チャットのアプリがリンクを開いて中身を見るなど) で、誰も意図しないまま処理が走ります。HTTP の仕様は、安全なメソッドで受けたときに安全でない操作をしてはならないと求めています。状態を変える操作には、POST・PUT・PATCH・DELETE を使ってください。
独自のステータスコードを作らない
「在庫切れ」に 460 のような独自のコードを割り当てても、クライアントの多くは知らないコードとして、分類の 400 と同じに扱います。独自のコードは、利用者が説明を読まない限り伝わりません。失敗の種類は、決まったステータスコードと、本文の中の情報で伝えます。本文の形は エラーの設計の章で決めます。
まとめ
- 利用者は API を使ってアプリを作る開発者と組織、クライアントは API を呼ぶプログラム、購入者は注文する人です
- メソッドはクライアントが何をしたいかを表します。新しいリソースの URL をサーバーが決めるなら POST、クライアントが決めた URL の状態を置き換えるなら PUT です
- 安全なメソッド (GET・HEAD・OPTIONS) は読み取り専用、冪等なメソッド (安全なメソッドと PUT・DELETE) は何回送っても効果が同じです。POST と PATCH はどちらでもありません
- ステータスコードは 1 桁目で 5 つに分類されます。知らないコードは分類の x00 として扱われます
- 作成は 201 と
Location、使えないメソッドは 405 とAllowで知らせます - HEAD はヘッダだけを、OPTIONS は使えるメソッドを返します
- 何を受け付けて何を返すかがコードの中にしか無いと、利用者は試すしかありません。このガイドは、それを仕様として先に書きます
次に読む
前の章は HTTP の仕組み です。
次章 要件の整理 では、注文の API を作る最初の段として、誰が何のために使うかと、受け入れる条件を書きます。
練習問題
注文の取り消しを、ブラウザのリンクで押せるように GET /orders/123/cancel で作ると、何が起きうるでしょうか。どのメソッドを使うべきですか
解答例
GET は安全なメソッドとして扱われるので、検索エンジンの巡回、ブラウザの先読み、チャットのアプリのリンクの確認などが、人の操作なしにこの URL を開きえます。そのたびに注文が取り消されます。また、通信が切れたときに、クライアントや中継の仕組みが GET を自動で送り直すこともあります。
取り消しは状態を変える操作なので、安全でないメソッド (POST など) を使います。どのメソッドと URL で表すかには、いくつかの設計があり、第 4 部で比べて決めます。
商品を作るリクエストで name が空文字のとき、400 と 422 のどちらを返すべきでしょうか。この章の情報で決まることと、決まらないことを分けて答えてください
解答例
決まること: 本文が JSON として読めないなら、構文の誤りなので 400 です。Content-Type が JSON でないなら、形式を受け付けないので 415 です。HTTP の仕様は 422 を「形式を理解でき構文も正しいが、中身を処理できない」場合と定めています。name が空文字の JSON は、この定義に当てはまります。
決まらないこと: それでも 400 を使う設計もあり、どちらを選ぶかは仕様の定義だけでは決まりません。決めるときに大事なのは、同じ API の中で同じ種類の失敗に同じコードを返すことと、利用者が失敗の中身を本文から読み取れることです。このガイドは、エラーの設計の章で、スタイルガイドを比べて決めます。
この章のサーバーのコード
商品のサーバーのコードです。読まなくても本文は追えます。
/*
* 商品を ID と名前だけで持つ、手書きのサーバー。3 章でメソッドとステータスコードを観察するのに使う。
* 設計した 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';
}
async function createProduct(req: IncomingMessage, res: ServerResponse): Promise<void> {
if (!isJson(req.headers['content-type'])) {
sendJson(res, 415, { message: '本文は application/json で送ってください' });
return;
}
let body: string;
try {
body = await text(req);
} catch {
// 本文を受け取る途中で接続が切れた。応答を返す相手がいないので、接続を閉じて終える。
res.destroy();
return;
}
let input: unknown;
try {
input = JSON.parse(body);
} catch {
sendJson(res, 400, { message: '本文が JSON として読めません' });
return;
}
const name = typeof input === 'object' && input !== null && 'name' in input ? input.name : undefined;
if (typeof name !== 'string' || name === '') {
sendJson(res, 400, { message: 'name を文字列で指定してください' });
return;
}
const product = { id: `p-${nextNumber++}`, name };
products.push(product);
sendJson(res, 201, product, { Location: `/products/${product.id}` });
}
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 });
}
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} で起動しました`);
});
URL のパスとメソッドで処理を分け、メソッドが合わないときに 405 と Allow を返しています。HEAD は GET と同じ処理に通し、本文を送らないのは Node.js に任せています。