REST API命名規則ガイド：「名詞」が推奨される理由と個人開発での現実的な落とし所【動詞 vs 名詞を整理する】

APIを自分で設計するとき、こんな悩みにぶつかったことはないでしょうか。
「/getTemperature にするか /temperature にするか、どっちが正しいんだろう？」
調べてみると「APIの名称は名詞にするのが正しい」という記述がたくさん出てきます。理屈は分かる。でも実際に /temperature とだけ書いてあると、それが何をするAPIなのか直感的につかみにくい——そんなモヤモヤを感じたことがある方は多いのではないでしょうか。
本記事ではREST APIの命名規則をあらためて整理し、「名詞が推奨される理由」と「動詞を使いたくなる感覚の正体」、そして個人開発でも崩れない実践的な命名ルールをまとめます。

なぜ命名規則について記事にしたのか？
実現したいこと
この記事でわかること
必要な準備と用意するもの
REST APIの命名規則：名詞が推奨される理由
1. URLは「リソース」を表し、HTTPメソッドが「アクション」を表す
2. 名詞ベースにすると「予測可能性」が上がる
「動詞がないと分かりにくい」という感覚の正体
1. 原因① HTTPメソッドが見えていない
2. 原因② CRUD操作に当てはまらない処理がある
動詞を使ってよいケースと使い方
1. CRUD以外の操作（カスタムアクション）
実践的なAPI命名ルール
当ラボの考え：命名規則に向き合う姿勢について
命名規則チートシート
まとめ

なぜ命名規則について記事にしたのか？

スマートホームのAPIをいくつか自分で設計してきた中で、命名規則について何度も手が止まりました。
変数名一つにも悩む性格なので、APIのエンドポイント名はなおさらです。
個人開発だと「とりあえず動けばいい」という気持ちで命名が雑になりがちですが、後から見返したとき・別のスクリプトから呼び出すときに「このAPIは何をするんだったっけ？」と迷うのは非常にストレスです。
ソースを長く、きれいに保つためには、最初から統一感のある命名規則を決めて守り続けることが大切だと感じています。

「名詞がいい」と分かっても動詞がないと落ち着かない……この感覚、整理したい！

実現したいこと

「名詞 vs 動詞」論争に自分なりの答えを出す
個人開発でも崩れない、統一感のあるAPI命名ルールを確立する
後から見返しても迷わない、読みやすいAPIを設計する

この記事でわかること

REST APIの命名で「名詞」が推奨される理由
動詞を使いたくなる感覚がなぜ生まれるのか
Good / Bad の具体的な命名例
個人開発での現実的な命名ルールと「統一感」の作り方

必要な準備と用意するもの

前提知識

HTTP メソッド（GET / POST / PUT / DELETE）の基本的な使い方を知っている
自分でAPIを設計・実装した経験がある（または予定がある）

開発環境（例）

Python（Flask / FastAPI）など何らかのWebフレームワーク
APIのテストツール（curl / Postman / HTTPie など）

REST APIの命名規則：名詞が推奨される理由

URLは「リソース」を表し、HTTPメソッドが「アクション」を表す

REST（Representational State Transfer）の設計原則では、URLは 「何に対して操作するか（リソース）」 を示し、「どういう操作をするか（アクション）」はHTTPメソッドで表現する という考え方をとります。

この役割分担が徹底されていれば、URL側に動詞を入れる必要がなくなります。

HTTPメソッド	意味	エンドポイント例	何をするか
GET	取得	/devices	デバイス一覧を取得する
POST	作成	/devices	新しいデバイスを登録する
GET	取得	/devices/{id}	指定デバイスの情報を取得する
PUT	更新	/devices/{id}	指定デバイスの情報を更新する
DELETE	削除	/devices/{id}	指定デバイスを削除する

上記のように、同じURL（/devices）に対してHTTPメソッドを変えるだけで複数の操作を表現できます。URLに get や create を入れると「GETメソッドでアクセスする /getDevices」のように、動詞が2重に存在することになります。

Good：名詞ベース（推奨）
GET /devices　→ デバイス一覧を取得
POST /devices　→ デバイスを登録
DELETE /devices/{id}　→ 指定デバイスを削除

Bad：動詞が混入している例
GET /getDevices　→ “GET” と “get” が重複
POST /createDevice　→ “POST” と “create” が重複
GET /deleteDevice/{id}　→ GETで削除？意味が矛盾する

名詞ベースにすると「予測可能性」が上がる

名詞ベースのAPI設計は、エンドポイントの 予測可能性（Predictability） が高まるという大きなメリットがあります。
/devices というエンドポイントを知っていれば、/devices/{id}/sensors というネスト構造も自然に予測できます。
動詞混じりの設計だと、同じリソースでも /getDeviceSensors・/fetchSensorList・/getSensorsForDevice などとバラバラになりやすく、APIが増えるほど混乱が大きくなります。

「動詞がないと分かりにくい」という感覚の正体

名詞ベースの理屈は理解できても、「/temperature だけだと何をするAPIか分からない気がする……」という感覚が消えない方は多いと思います。この感覚、実は間違っていません。
この感覚が生まれる原因は主に2つあります。

原因① HTTPメソッドが見えていない

URLだけを見ていると「アクション」の情報が欠けているように感じます。しかし実際にAPIを呼び出す側は、必ずHTTPメソッドとセットで エンドポイントを指定します。
GET /temperature と POST /temperature は全く別の操作であり、その区別はHTTPメソッドが担っています。ドキュメントやコードを見るときも「メソッド＋URL」をセットで認識する習慣をつけると、違和感がなくなります。

SwaggerなどのドキュメントツールがメソッドとURLをセットで色分け表示するのはこのためです。APIドキュメントを整備する習慣をつけると「名詞だけで意味が通る」感覚が身につきます。

原因② CRUD操作に当てはまらない処理がある

もう一つの原因は、純粋なCRUD（作成・取得・更新・削除）に当てはまらない処理 の場合です。たとえば「デバイスのスイッチをオンにする」「通知を送信する」「電力量を集計する」といった操作は、HTTPメソッドだけでは意味を表しにくく、URLに動詞を入れたくなるのは自然な発想です。

このような「CRUD以外の操作」に動詞を使うことはRESTの文脈でも一定程度許容されており、著名なAPI設計ガイドライン（Google Cloud API DesignやMicrosoft REST API Guidelines）でも「カスタムメソッド」として動詞の使用を認めています。

動詞を使ってよいケースと使い方

CRUD以外の操作（カスタムアクション）

次のようなケースは名詞だけでは表現が難しいため、動詞を含めることが現実的です。

操作	推奨パターン	説明
デバイスをオンにする	POST /devices/{id}/activate	サブリソースとして動詞を末尾に置く
照明を消す	POST /lights/{id}/turn-off	同上
通知を送る	POST /notifications/send	操作自体が「送信」なので動詞OK
電力量を集計する	GET /power/summary	名詞で言い換えられる場合は名詞優先
キーワード検索	GET /devices/search?q=xxx	検索はGETのクエリパラメータで表現

カスタムアクションは「リソース名/{id}/動詞」の形にまとめる
POST /devices/{id}/activate のようにリソースを先に置き、末尾のサブリソースとして動詞を使うパターンが最も多くのガイドラインで推奨されています。URL全体の構造的な一貫性が保たれます。

動詞をURL先頭に置くのは避ける
POST /activateDevice/{id}・GET /getDeviceStatus/{id} のように動詞が先頭に来るとリソース中心の構造が崩れ、エンドポイントが増えるにつれて命名の一貫性が失われます。

実践的なAPI命名ルール

① コレクションには複数形の名詞を使う

一覧を返すエンドポイントは複数形にするのが一般的です。

Good
GET /devices　（デバイス一覧）
GET /sensors　（センサー一覧）

Bad
GET /device　（単数形。一覧なのか1件取得なのか曖昧）

② すべて小文字・単語の区切りはハイフン

URLは大文字小文字が区別されることがあるため、すべて小文字で統一します。単語の区切りにはハイフン（ケバブケース）を使うのがWeb標準に沿った書き方です。

Good
/power-consumption
/room-temperature

Bad
/powerConsumption　（キャメルケース：URLに不向き）
/power_consumption　（スネークケース：URLでは非推奨）
/PowerConsumption　（パスカルケース：URLに不向き）

③ 階層はスラッシュで表現する（ネストは浅く）

リソース間の親子関係はスラッシュで階層化します。ただし深くなりすぎると可読性が下がるため、2〜3階層を目安にします。

# 良い例：2階層まで
GET /rooms/{id}/sensors          # 部屋に紐づくセンサー一覧
GET /devices/{id}/logs           # デバイスのログ一覧

# 深くなりすぎる例（避ける）
GET /buildings/{id}/floors/{id}/rooms/{id}/devices/{id}/sensors
# → クエリパラメータで代替を検討する
GET /sensors?room_id={id}

④ フィルター・ソートはクエリパラメータで表現する

「有効なデバイスだけ取得」「名前順で取得」などの絞り込みはURLパスに含めず、クエリパラメータで表現します。

# 良い例：クエリパラメータで絞り込み
GET /devices?status=active
GET /devices?sort=name&order=asc
GET /logs?from=2026-01-01&to=2026-05-31

# 避けるべき例：絞り込み条件をパスに入れている
GET /devices/active
GET /devices/sorted-by-name

⑤ バージョニングをURLに含める

将来のAPI変更に備えてバージョン番号をURLに含めておくと、後から既存クライアントを壊さずにAPI改修ができます。

GET /api/v1/devices
GET /api/v1/devices/{id}/sensors

# v2で仕様変更しても v1 のクライアントに影響しない
GET /api/v2/devices

個人開発の場合、最初から /api/v1/ を付けておくと将来の改修がずっと楽になります。「まだv1しかないし不要かな」と思っても、最初に付けておくことを強くおすすめします。

当ラボの考え：命名規則に向き合う姿勢について

「名詞が正しい」という原則は理解しつつも、動詞がないと落ち着かない——この感覚は決して間違いではありません。
重要なのは、迷いそうな点を事前に決めておき、プロジェクト全体で一貫して守ること です。

個人的に考えるAPI命名の優先順位は以下のとおりです。

一貫性（プロジェクト内でルールがブレない）
可読性（見た瞬間にリソースと操作がイメージできる）
標準への準拠（REST原則に沿っている）

「名詞で統一する」という原則に従いながら、CRUDに当てはまらない操作だけ /リソース/{id}/動詞 の形で動詞を許容する——この落とし所が個人開発では最も現実的でおすすめです。
重要なのは「完全に正しい命名をするか」ではなく、「自分（とチーム）が決めたルールをどのAPIでも同じように適用できているか」 です。
命名規則は一度決めたら全APIで統一し、新しいエンドポイントを追加するときも必ず同じルールを参照する習慣をつけましょう。

変数名やAPIの命名に時間をかけることは「こだわりすぎ」ではありません。コードは書いた後に何十回・何百回と読まれます。名前に1分かけることで、後のすべての読み手の時間を節約できます。個人開発でも同じです。

命名規則チートシート

以下に、本記事でまとめたAPI命名ルールをチートシートとしてまとめます。

ルール	Good	Bad
名詞ベース（CRUD）	GET /devices	GET /getDevices
複数形	/devices	/device
小文字＋ハイフン	/room-temperature	/roomTemperature
階層はスラッシュ	/devices/{id}/logs	/getDeviceLogs/{id}
絞り込みはクエリパラメータ	/devices?status=active	/devices/active
バージョニング	/api/v1/devices	/devices（バージョン未指定）
カスタムアクション	POST /devices/{id}/activate	POST /activateDevice/{id}