HTTP の仕組み: リクエストとレスポンスを curl で見る
前の章で、Web API は Web のページと同じ通信の仕組みを使う API だと説明しました。その仕組みが HTTP です。この章では、受け取ったリクエストをそのまま JSON にして返すサーバー (エコーサーバー) を動かし、curl で送ったものとサーバーに届いたものを見比べながら、HTTP のメッセージの形を確かめます。
この章で扱うのは、API を設計するときに毎回使う部分だけです。HTTP をもっと詳しく知りたいときは、Web エンジニア基礎知識ガイドの HTTP の章を読んでください。
クライアントとサーバー
HTTP では、通信を始める側をクライアント、待ち受けて答える側をサーバーと呼びます。クライアントはリクエストのメッセージを送り、サーバーはレスポンスのメッセージで答えます。1 つのリクエストに 1 つのレスポンスが返るのが基本の形です。
前の章の例では、スマートフォンのアプリがクライアントで、店のサーバーがサーバーです。この章では curl がクライアントになり、エコーサーバーがサーバーになります。
エコーサーバーを起動する
サンプルリポジトリの rest-02-r2 に切り替えて、エコーサーバーを起動します。
node tools/echo-server/server.ts
エコーサーバーを http://localhost:3901 で起動しました
エコーサーバーは、受け取ったリクエストのメソッド・URL・ヘッダ・本文を、そのまま JSON にして返します。設計した API ではなく、HTTP を観察するための道具です。コードは章末の「この章のサーバーのコード」にあります。
サーバーは起動したまま止まりません。以降の curl は、別のターミナルを開いて打ってください。サーバーを止めるときは、起動したターミナルで Ctrl+C を押します。
URL の部分
まず、URL に問い合わせの文字列を付けて送ります。
curl -s 'http://localhost:3901/orders?status=PENDING'
{
"method": "GET",
"url": "/orders?status=PENDING",
"headers": {
"host": "localhost:3901",
"user-agent": "curl/8.18.0",
"accept": "*/*"
},
"body": ""
}
送った URL http://localhost:3901/orders?status=PENDING は、次の部分からできています。
| 部分 | この例 | 意味 |
|---|---|---|
| スキーム | http | 通信の方式。http か https |
| ホスト | localhost | 接続するサーバーの名前 |
| ポート | 3901 | サーバーが待ち受ける番号。省くと http は 80、https は 443 |
| パス | /orders | サーバーの中の、どのリソースかを表す |
| クエリ | status=PENDING | ? の後ろの、名前と値の組 |
結果の url を見ると、サーバーに届いたのはパスとクエリだけで、スキーム・ホスト・ポートを含みません。HTTP/1.1 でサーバーへ直接送るリクエストでは、接続先はすでに決まっているので、開始行にはパスとクエリだけを書き、ホストは Host ヘッダで別に伝えます。届いたヘッダの host がそれです。
URL を単一引用符で囲んだのは、シェルが ? を特別な文字として読むからです。zsh (macOS の既定のシェル) は、引用符で囲まない ? をファイル名の候補として展開しようとし、一致するファイルが無いと誤りにして curl を動かしません。このガイドの curl の例は、? を含む URL をいつも単一引用符で囲みます。
リクエストとレスポンスの形
HTTP/1.1 のメッセージは、次の 4 つの部分からなります。
- 開始行: リクエストなら「メソッド、対象、HTTP のバージョン」、レスポンスなら「HTTP のバージョン、ステータスコード、理由句」
- ヘッダ:
名前: 値の行の並び。名前は大文字と小文字を区別しない - 空行: ヘッダの終わりを示す
- 本文: 送るデータ。無いこともある
curl に -v を付けると、送ったリクエストと受け取ったレスポンスの開始行とヘッダが見えます。
curl -s -v http://localhost:3901/orders -o /dev/null
* Host localhost:3901 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* Trying [::1]:3901...
* Established connection to localhost (::1 port 3901) from ::1 port 40852
* using HTTP/1.x
> GET /orders HTTP/1.1
> Host: localhost:3901
> User-Agent: curl/8.18.0
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 159
< Date: Sat, 31 Oct 2026 09:00:00 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
{ [159 bytes data]
* Connection #0 to host localhost:3901 left intact
行の頭の記号は、> が curl の送ったヘッダ、< が受け取ったヘッダ、* が curl の補足の情報です。-o /dev/null は本文を捨てる指定で、ここではヘッダだけを見るために付けました。
> の行を並べると、curl が送ったリクエストのメッセージになります。
GET /orders HTTP/1.1
Host: localhost:3901
User-Agent: curl/8.18.0
Accept: */*
1 行目の開始行は、メソッド (GET)、対象 (/orders)、HTTP のバージョン (HTTP/1.1) の順です。この例では本文が無いので、空行で終わります。
-v の出力は、curl の版や接続先 (IPv4 か IPv6 か) で行が変わります。レスポンスのヘッダと本文だけを見たいときは、-i を使います。
curl -s -i http://localhost:3901/orders
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 159
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{
"method": "GET",
"url": "/orders",
"headers": {
"host": "localhost:3901",
"user-agent": "curl/8.18.0",
"accept": "*/*"
},
"body": ""
}
1 行目がレスポンスの開始行で、HTTP のバージョン (HTTP/1.1)、ステータスコード (200)、理由句 (OK) の順です。ステータスコードはリクエストの結果を表す 3 桁の数で、200 は成功を表します。理由句は人が読むための添え書きで、HTTP/1.1 の仕様 (RFC 9112) は、クライアントが理由句の中身を当てにしないよう求めています。結果を判断するのは数のほうです。ステータスコードの意味は次の章で扱います。
ヘッダの後の空行を挟んで、本文の JSON が続きます。
curl の使い方
このガイドで使う curl の option をまとめます。
| option | 意味 |
|---|---|
-s | 進み具合や誤りの表示を消し、受け取った本文だけを出す |
-i | レスポンスの開始行とヘッダも、本文と一緒に出す |
-I | HEAD のメソッドで送り、ヘッダだけを受け取る |
-v | 送ったものと受け取ったものの詳細を出す (標準エラー出力) |
-X <メソッド> | メソッドを指定する |
-H '<名前>: <値>' | ヘッダを足す。同じ名前のヘッダを curl が自分で付ける場合は、指定した値を使う |
-d '<データ>' | 本文を送る。メソッドは POST になる |
-o <ファイル> | 本文を、画面でなくファイルに書く |
-w '<書式>' | 送り終えた後に、書式に従って情報を出す |
本文を送ってみます。-d で JSON を渡し、-H で本文の形式を知らせます。
curl -s http://localhost:3901/orders \
-H 'Content-Type: application/json' \
-d '{"productId":"p-1","quantity":2,"note":"贈り物"}'
{
"method": "POST",
"url": "/orders",
"headers": {
"host": "localhost:3901",
"user-agent": "curl/8.18.0",
"accept": "*/*",
"content-type": "application/json",
"content-length": "51"
},
"body": "{\"productId\":\"p-1\",\"quantity\":2,\"note\":\"贈り物\"}"
}
-X POST を書かなくても、-d があればメソッドは POST になります。curl は、GET・HEAD・POST・PUT をそれぞれ専用の option (何も付けない・-I・-d・-T) で送ります。-X が要るのは、DELETE や OPTIONS のように専用の option が無いメソッドで送るときと、PUT や PATCH で JSON の本文を -d で送るときです。行末の \ は、コマンドを次の行に続ける書き方です。\ の後ろに空白を置くと続かなくなるので注意してください。
-d は、Content-Type を指定しないと、HTML のフォームと同じ形式の値を付けて送ります。
curl -s http://localhost:3901/orders -d 'quantity=2'
{
"method": "POST",
"url": "/orders",
"headers": {
"host": "localhost:3901",
"user-agent": "curl/8.18.0",
"accept": "*/*",
"content-length": "10",
"content-type": "application/x-www-form-urlencoded"
},
"body": "quantity=2"
}
JSON を送るのに -H 'Content-Type: application/json' を付け忘れると、サーバーには「フォームの形式」と伝わります。JSON を受け付ける API は、こうしたリクエストを断ることが多いので、JSON を送る例ではいつも Content-Type を付けます。
ステータスコードだけを見たいときは、-w を使います。
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3901/orders
200
%{http_code} は最後に受け取ったステータスコードで、\n は改行です。curl の文書は今は同じ値を %{response_code} の名前で説明していて、http_code はその旧い名前です。どちらでも同じ値になります。サンプルリポジトリの手書きのサーバー (この章と次の章のもの) は本文の最後に改行を付けるので、本文の後にステータスコードを並べたいときは -w '%{http_code}\n' を使います。本文の最後に改行を付けないサーバー (モックの章の Prism など) では、-w '\n%{http_code}\n' のように前にも改行を書きます。
よく使うヘッダ
ヘッダは、メッセージの本文の外で、本文の形式や長さ、日時などを伝えます。API でよく使うものを挙げます。
| ヘッダ | 向き | 中身 |
|---|---|---|
Host | リクエスト | 接続先のホストとポート。curl が自分で付ける |
User-Agent | リクエスト | クライアントの名前と版。curl が自分で付ける |
Content-Type | 両方 | 本文の形式 (メディアタイプ) |
Content-Length | 両方 | 本文の長さ (バイト数) |
Accept | リクエスト | レスポンスに望む形式 |
Date | レスポンス | メッセージを作った日時 |
Content-Length は文字数ではなくバイト数です。上の JSON の例の結果の content-length は、本文の文字数より大きな値になっています。贈り物 の 3 文字が、UTF-8 で 1 文字 3 バイトになるためです。
Accept は、レスポンスに望む形式をサーバーに伝えます。curl は何も指定しないと */* (どの形式でもよい) を送ります。
curl -s http://localhost:3901/orders -H 'Accept: application/json'
{
"method": "GET",
"url": "/orders",
"headers": {
"host": "localhost:3901",
"user-agent": "curl/8.18.0",
"accept": "application/json"
},
"body": ""
}
エコーサーバーは Accept を見ずに JSON を返しますが、Accept に合う形式を返せないとき、サーバーはそう知らせる応答を返せます。そのステータスコードと、API が Accept をどう扱うかは、表現の設計の章で扱います。
JSON とメディアタイプ
Content-Type の値 application/json はメディアタイプです。種類/詳細 の形で、データの形式と、受け取った側がそれをどう扱うかを示します。HTML なら text/html、フォームの値なら application/x-www-form-urlencoded です。
このガイドの API は、本文に JSON を使います。JSON は、言語に依存しないテキストのデータ交換の形式で、次の値を表せます。
{
"name": "りんご",
"price": 120,
"tags": ["果物", "赤"],
"inStock": true,
"note": null
}
- オブジェクト (
{}): 名前と値の組の集まり。順序は意味を持たない - 配列 (
[]): 値の並び。順序を持つ - 文字列・数値・真偽値 (
true・false)・null
JSON の仕様 (RFC 8259) から、API で守ることを挙げます。
true・false・nullは小文字で書く- 1 つのオブジェクトの中で、名前を重ねない。重なったときの扱いは受け取る側のソフトウェアで違う
- 閉じた環境の外のシステムとやり取りする JSON は、UTF-8 で符号化する
- メディアタイプは
application/jsonで、charsetの指定は定義されていない (付けても効果が無い)
ステートレス
HTTP はステートレスなプロトコルとして定義されています。HTTP の仕様 (RFC 9110) は、各リクエストの意味がそれ単体で理解でき、同じ接続で前に送ったリクエストがその解釈に影響しない、と書いています。
エコーサーバーで確かめた範囲でも、サーバーは前のリクエストを何も覚えていません。2 回目のリクエストで status=PENDING を省いても、サーバーは 1 回目の値を補いません。
REST の考え方は、これを API の設計の制約として求めます。クライアントからのリクエストは、それを理解するのに要る情報をすべて含み、サーバーに保存した「会話の文脈」を当てにしない、という制約です。ログインした人の識別も、リクエストごとに送ります (第 5 部で扱います)。
この制約の利点は、サーバーがリクエストごとに独立して処理できることです。どのサーバーがリクエストを受けても同じように処理できるので、サーバーの台数を増やしやすく、障害のときの切り替えも単純になります。代わりに、同じ情報 (認証の情報など) を毎回送るので、メッセージは長くなります。
HTTP のバージョンと HTTPS
HTTP には HTTP/1.1・HTTP/2・HTTP/3 のバージョンがあり、今はどれも使われています。3 つは通信路の上でのメッセージの表し方 (行の書式と、接続の使い方) が違いますが、メソッド・ステータスコード・ヘッダの意味は共通で、同じ仕様 (RFC 9110) に従います。
このガイドが扱うのは、この共通の意味の層です。API の設計で決める URL・メソッド・ステータスコード・ヘッダは、どのバージョンで運ばれても同じ意味になります。この章で見た開始行の形は HTTP/1.1 の書き方で、HTTP/2 と HTTP/3 では同じ情報を別の形で運びます。
HTTPS は、TLS で保護した接続の上で HTTP を使う方式で、URL のスキームは https、ポートの既定は 443 です。HTTPS では、サーバーが URL のホストの持ち主として認証され、通信の中身は盗み見と書き換えから守られます。このガイドの例は手元のサーバーなので http://localhost を使いますが、インターネットに公開する API は HTTPS で提供します。
記事の結果の読み方
この章から、記事に載せた curl の結果は、サンプルリポジトリのテストが同じ curl を実行して確かめたものです。そのため、実行のたびに変わる値は、決まった値に置き換えて載せています。
Dateヘッダ: 実際の日時の代わりに、決まった日時を載せていますUser-Agent: テストは curl の設定ファイルで決まった値を送ります。手元では、入っている curl の版になります。エコーサーバーはこの値を本文に入れるので、版の文字数が違うと、-iの例のContent-Lengthも変わります
テストは、章ごとにサーバーを 1 回起動し、記事の例を記事の順に送ります。照合しないと断った例 (-v の例) を除き、サーバーを起動した直後から記事の順に打てば、この 2 つのほかは記事と同じ結果になります。次の章で商品を作る例のように、サーバーの状態を変える例もあります。途中でサーバーを起動し直したり同じ例を 2 回打ったりすると、その後の結果は記事と変わります。手元の curl の設定ファイル (~/.curlrc) でヘッダを足していると、その分も結果に表れます。
実務で効く注意点
-d は既定でフォームの形式を名乗る
curl の -d は、Content-Type を指定しないと application/x-www-form-urlencoded を付けます。JSON を送ったつもりでもサーバーにはフォームの形式と伝わり、API が断る原因になります。API を curl で試すときは、JSON を送る例に -H 'Content-Type: application/json' を必ず付けてください。手順書や README に curl の例を書くときも同じです。
-v の出力をそのまま共有しない
-v は送ったヘッダをすべて出すので、認証の情報 (Authorization ヘッダのトークンなど) もそのまま表示されます。不具合の相談のために出力を貼るときは、こうしたヘッダの値を消してから共有してください。
まとめ
- HTTP では、クライアントがリクエストを送り、サーバーがレスポンスで答えます
- URL はスキーム・ホスト・ポート・パス・クエリからなり、リクエストの開始行に入るのはパスとクエリです。ホストは
Hostヘッダで伝えます - メッセージは、開始行・ヘッダ・空行・本文からなります。レスポンスの開始行のステータスコードが結果を表します
- curl は
-s・-i・-v・-X・-H・-d・-wを使い分けます。-dだけでは JSON と伝わらないので、Content-Typeを付けます - 本文の形式は
Content-Typeのメディアタイプで、長さはContent-Lengthのバイト数で伝えます。このガイドの API はapplication/jsonを使います - HTTP はステートレスです。リクエストは、理解に要る情報をすべて含みます
- HTTP/1.1・2・3 は意味が共通で、このガイドの設計はこの意味の層で行います。公開する API は HTTPS で提供します
次に読む
前の章は はじめに です。
次章 メソッドとステータスコード では、リクエストの開始行のメソッドと、レスポンスの開始行のステータスコードが、それぞれ何を意味するかを扱います。
HTTP のヘッダやキャッシュをもっと詳しく知りたいときは、Web エンジニア基礎知識ガイドの HTTP の章を読んでください。
練習問題
JSON を受け付ける API が、リクエストの Content-Type を見ずに、本文が JSON として読めるかだけで受け付けるかを決めると、何が困りますか
解答例
クライアントが本文の形式を取り違えても、たまたま JSON として読める中身なら受け付けてしまい、取り違えに気づく機会がなくなります。curl の -d で Content-Type を付け忘れたリクエストは、フォームの形式を名乗ったまま届きます。API が Content-Type を見て「JSON 以外の形式は扱わない」と明示的に断れば、クライアントの開発者は原因をすぐに知れます。
また、Content-Type は将来の拡張の手がかりにもなります。同じ URL で別の形式 (たとえば CSV) を受け付けたくなったとき、Content-Type で見分けていれば、既存のクライアントの動きを変えずに足せます。
HTTP がステートレスであることを前提に、「購入者が直前に見ていた注文」をアプリの次の画面で使いたいとき、その情報はどこに置きますか
解答例
置き場は 2 つ考えられます。
1 つはクライアントです。アプリが直前に見た注文の ID を覚えておき、次の画面のリクエストにその ID を含めて送ります。サーバーは、届いたリクエストだけで処理できます。
もう 1 つは、サーバー側のリソースとして保存することです。たとえば「最近見た注文」を購入者ごとのリソースとして保存し、URL で取り出せるようにします。この場合も、リクエストは購入者を識別する情報を毎回含み、サーバーは接続や直前のリクエストを覚えておく必要がありません。
避けるのは、サーバーが「この接続の直前のリクエスト」を覚えていて、それを前提に次のリクエストを解釈する形です。別のサーバーにリクエストが振り分けられたときに、前提が崩れます。
この章のサーバーのコード
エコーサーバーのコードです。TypeScript で書いてあり、Node.js が型の注釈を取り除いてそのまま実行します。読まなくても本文は追えます。
/*
* 受け取ったリクエストのメソッド・URL・ヘッダ・本文を、そのまま JSON にして返すサーバー。
* 2 章で、curl が何を送っているかを観察するのに使う。設計した API ではない。
*/
import { createServer } from 'node:http';
import { text } from 'node:stream/consumers';
const port = 3901;
createServer(async (req, res) => {
let body: string;
try {
body = await text(req);
} catch {
/*
* 本文を受け取る途中で接続が切れた。応答を返す相手がいないので、接続を閉じて終える。
* 捕まえないと、この async の関数の外で処理されないまま、サーバーのプロセスが止まる。
*/
res.destroy();
return;
}
const echo = { method: req.method, url: req.url, headers: req.headers, body };
const json = `${JSON.stringify(echo, null, 2)}\n`;
/*
* writeHead でヘッダを決めてから本文を渡すので、Content-Length を書かないと、Node.js は本文を chunked で送る。
* 長さを数えるのは文字でなくバイトで、日本語は 1 文字が複数のバイトになる。
*/
res.writeHead(200, {
'Content-Type': 'application/json',
'Content-Length': Buffer.byteLength(json),
});
res.end(json);
}).listen(port, () => {
console.log(`エコーサーバーを http://localhost:${port} で起動しました`);
});
createServer に渡した関数が、リクエストを受けるたびに呼ばれます。req が受け取ったリクエスト、res が返すレスポンスです。req.headers のヘッダの名前は、Node.js がすべて小文字にそろえます。HTTP のヘッダの名前は大文字と小文字を区別しないので、比べやすい形にそろえています。