REST APIの考え方を図にした。URLに動詞を入れない

• RESTは一連の制約条件を指す言葉
• URLは物を指す。動作はメソッドで表す
• RESTfulと呼ばれるAPIが、必ずしも準拠しているとは限らない

API設計の話で必ず出てくるが、言葉の定義が曖昧なまま使われていることが多い。整理する。

そもそも何を指す言葉か

MDNの用語集はこう定義している。

REST（Representational State Transfer）は、効率的で信頼性が高く、スケーラブルな分散システムを実現するためのソフトウェアアーキテクチャ設計上の一連の制約条件のことです。

そして基本的な考え方として、リソース（たとえば文書）が、よく認識され、言語にとらわれず、確実に標準化されたクライアント/サーバーのやりとりで転送されることが挙げられている。

「これらの制約に準拠している場合、RESTfulとみなされる」という書き方になっている。つまりRESTは形式ではなく条件だ。

URLは物を指す

同じURLでも、メソッドが違えば意味が変わる。/articles/42 という住所に対して、取るのか、置き換えるのか、消すのかをメソッドで示す。

動詞をURLに入れるとどうなるか

操作のたびにURLが増える。

• 操作の数だけ覚えることが増える
• 何ができるかを一覧できない
• 似た名前が並ぶ（getArticle と fetchArticle が両方ある、など）

物を指す形にすると、URLは物の住所、できることはメソッドの数に収まる。新しい物が増えてもURLの付け方は変わらない。

前のやり取りを覚えない前提

RESTが乗っているHTTPは、MDNの表現でステートレスだ。「同じコネクション上であっても、連続的に実行される2つのリクエスト間に関係性はありません」とされている。

この前提に乗ると、1回のリクエストだけを見て処理を決められる。前の状態を覚えておく必要がないので、サーバーを増やしても同じ結果になる。

逆に、途中の状態をサーバー側に持たせる設計にすると、台数を増やしたときに同じ機械に当て続ける必要が出てくる。

ここが実務での注意点

MDNは、現状についてもはっきり書いている。

一般的に HTTP API は、俗に RESTful API、RESTful サービス、REST サービスなどと呼ばれることがありますが、必ずしも REST のすべての制約に準拠しているわけではありません。

そして初心者向けの案内として、「REST APIとは、標準的なウェブライブラリーやツールを使って呼び出すことができるHTTPサービスのこと」と捉えてよい、とも書かれている。

つまり「REST API」と書いてあっても、厳密な意味での準拠は期待しないほうがよい。使う側としては、実際の仕様書を読むことになる。

使う側として見るところ

APIを使うとき、呼び名より次を確認する。

1. URLの付け方 — 物を指しているか、動詞が入っているか
2. メソッドの使い分け — 取得が GET になっているか
3. 返る番号 — 成功と失敗が番号で区別されているか。何でも200で返すAPIもある
4. エラーの形 — 失敗時の中身が決まっているか
5. 繰り返しても安全か — 同じ要求を2回送ったときに二重に処理されないか

5番が実務で効く。通信が途中で切れたとき、送り直してよいかどうかが変わる。

まとめ

• RESTは制約条件の集まり。準拠していればRESTfulと呼ばれる
• URLは物を指す。動作はメソッドで表す
• 動詞をURLに入れると、操作の数だけURLが増える
• HTTPがステートレスなので、1回の要求だけで処理を決められる
• RESTfulと呼ばれていても、全制約に準拠しているとは限らない
• 使う側は呼び名より、繰り返し送って安全かなどを確認する

出典

• MDN「REST」（定義、RESTfulの条件、実際のHTTP APIについての注記）
• MDN「HTTP の概要」（ステートレス性）

図は本記事のために作成したもの。本記事は2026年10月13日時点の内容に基づく。