【入門編】リソース指向設計(ROA)における名詞の活用 – Web APIアーキテクチャ・データ連携実践ガイド

URLは「住所」であって「命令」ではない！リソース指向設計（ROA）で美しいAPIを作るコツ

こんにちは！ネットワークの世界にどっぷり浸かって十数年、パケットの呼吸音すら聞こえてきそうな現場のエンジニアです。

今日は、Web APIの設計において「これだけは守ってほしい！」という黄金律、リソース指向設計（ROA: Resource Oriented Architecture）についてお話しします。

APIを設計し始めたばかりの頃、「ユーザーを取得したいから /getUser にしよう！」「削除したいから /deleteUser だ！」と、URLに「動詞」を盛り込んでしまった経験はありませんか？

実はそれ、郵便配達に例えると少しだけ「惜しい」設計なんです。今日はその理由と、プロが現場で愛用する「美しいURL」の作り方を、一緒に紐解いていきましょう！

—

1. 郵便配達で考える「リソース」の考え方

想像してみてください。あなたは今、誰かに手紙を送ろうとしています。その時、封筒の宛名欄にこう書いたらどうでしょうか？

「田中さんの住所」の代わりに、「田中さんを読み取って」と書く。

配達員さんは困ってしまいますよね。「読み取る」というのは、あなたが田中さんに対して行いたい「アクション（動詞）」であって、田中さんという「実体（名詞）」そのものではないからです。

Webの世界もこれと同じです。

URL（住所）：そこに「何」があるか（リソース＝名詞）を示すもの
HTTPメソッド（手紙の封筒のラベル）：そこに「何をするか」（アクション＝動詞）を示すもの

この役割分担を明確にするのが、REST APIの美しい設計の第一歩なんです。

—

2. なぜ「名詞」で設計するのか？

もしURLに動詞を混ぜてしまうと、APIが増えるたびに「やりたいこと」の数だけURLが必要になり、管理が破綻します。

例えば、ユーザーを操作する場合を見てみましょう。

ダメな例（動詞が含まれている）

GET /getUsers （ユーザーを取得）
POST /createUser （ユーザーを作成）
POST /updateUser （ユーザーを更新）
POST /deleteUser （ユーザーを削除）

これだと、URLがバラバラで統一感がありませんよね。では、これを「名詞」だけで整理してみましょう。

美しい例（リソース指向）

GET /users （ユーザーの一覧を取得）
POST /users （ユーザーを新規作成）
GET /users/1 （IDが1のユーザー情報を取得）
PUT /users/1 （IDが1のユーザー情報を更新）
DELETE /users/1 （IDが1のユーザー情報を削除）

どうでしょう？URLはすべて「ユーザー（users）」という名詞に統一されています。その代わり、「何をするか」は GET や POST といった HTTPメソッドが担当してくれています。これが、世界中で使われている「REST APIの流儀」です。

—

3. 実践！リソース指向のコード設計

では、実際にAPIを作る際、どのような構成になるのかを見てみましょう。Pythonのフレームワーク（FastAPIなど）をイメージした例です。

# リソース指向を意識したエンドポイント設計例

# 1. ユーザー一覧を取得する (GETメソッド)
@app.get("/users")
def get_users():
    # データベースからユーザーリストを返す処理
    return {"message": "ユーザー一覧を返します"}

# 2. 新しいユーザーを作成する (POSTメソッド)
@app.post("/users")
def create_user():
    # ユーザーを作成する処理
    return {"message": "ユーザーを作成しました"}

# 3. 特定のユーザー情報を更新する (PUTメソッド)
@app.put("/users/{user_id}")
def update_user(user_id: int):
    # IDを基に特定のユーザーを更新する処理
    return {"message": f"ユーザーID {user_id} を更新しました"}

このように、URLは「場所」に集中させ、メソッドで「操作」を使い分ける。これだけで、他のエンジニアがコードを見たときに「次はここを叩けばいいんだな」と直感的に理解できるようになります。これが疎結合（お互いに依存しないきれいな関係）なシステムへの近道です。

—

4. 最後に：インフラ屋からのアドバイス

ネットワークスペシャリストの視点から一つ付け加えると、この「名詞ベースのURL設計」は、実はキャッシュの効率にも大きく関わっています。

GET /users/1 というURLであれば、ネットワーク機器やブラウザは「ああ、これはID 1のユーザーデータだな」と認識し、一度取得した内容を賢く保存（キャッシュ）してくれます。しかし、URLに ?action=getUser のような動詞が入り混じると、キャッシュがうまく効かなくなるケースがあるのです。

「美しいURL」は、見た目が整っているだけではありません。ネットワークの効率を最大化し、メンテナンスコストを最小化するための知恵なんです。

最初は難しく感じるかもしれませんが、まずは「URLには名詞だけを使う！」と決めてみてください。それだけで、あなたの書くAPIはグッとプロフェッショナルなものに変わりますよ。

一歩ずつ、一緒に学んでいきましょうね！また次回の記事でお会いしましょう。