REST設計って何？一言でいうと「URLとHTTPを“きれいなルール”で使う設計」
REST 設計は、Web API を作るときに、
URL
HTTPメソッド（GET / POST / PUT / PATCH / DELETE）
ステータスコード（200 / 201 / 400 / 404 など）
JSON などの表現形式
を「一貫したルール」で使うための考え方です。
ポイントは、「操作を動詞で並べる」のではなく、「リソース（もの）を名詞で表して、それに対して標準的な動詞（HTTPメソッド）を使う」という発想に切り替えることです。
「ユーザーを作るAPI」ではなく、「ユーザーというリソースに対する操作」として設計する、という感覚です。
RESTの基本：リソースを名詞で表し、HTTPメソッドで操作を表す
リソースをURLで表現する
RESTでは、「何に対する操作か」を URL で表します。
例えば、ユーザーとタスクを扱うサービスなら、こんな感じになります。
/users は「ユーザーの集合」/users/1 は「IDが1のユーザー」/tasks は「タスクの集合」/tasks/10 は「IDが10のタスク」
ここでは、URLは「名詞」で終わるのが基本です。/createUser や /deleteTask のように「動詞」をURLに入れるのは、REST的にはあまり良くありません。
「何をするか」は、HTTPメソッドで表すからです。
HTTPメソッドで「何をするか」を表す
代表的なメソッドの役割はこうです。
GET
リソースを取得する（読む）
POST
新しいリソースを作る、または「集合」に対して何かを追加する
PUT
リソースを「全体として」置き換える
PATCH
リソースの一部を更新する
DELETE
リソースを削除する
例えば、ユーザーに対してはこうなります。
GET /users
ユーザー一覧を取得する
POST /users
新しいユーザーを作る
GET /users/1
IDが1のユーザーを取得する
PATCH /users/1
IDが1のユーザーの一部を更新する（名前だけ変えるなど）
DELETE /users/1
IDが1のユーザーを削除する
「URLは名詞」「メソッドは動詞」という役割分担を守ると、REST設計は一気に分かりやすくなります。
具体例でREST設計を体感する：シンプルなTodo API
エンドポイントの設計
Todo アプリの REST API を考えてみます。
扱うリソースは「タスク（todo）」です。
リソースのURLはこう決めます。
/todos
タスクの集合
/todos/{id}
特定のタスク
これに HTTPメソッドを組み合わせて、操作を設計します。
GET /todos
タスク一覧を取得
POST /todos
新しいタスクを作成
GET /todos/1
IDが1のタスクを取得
PATCH /todos/1
IDが1のタスクの一部を更新（タイトル変更、完了フラグ変更など）
DELETE /todos/1
IDが1のタスクを削除
ここまでで、「URLとメソッドの組み合わせで操作を表現する」という REST の基本が見えてきます。
リクエストとレスポンスの例
新しいタスクを作るときのリクエストは、例えばこうです。
POST /todos
{
"title": "牛乳を買う"
}
レスポンスは、作成されたタスクを返します。
ステータスコード: 201 Created
{
"id": 1,
"title": "牛乳を買う",
"done": false
}
タスク一覧を取得するときは、
GET /todos
レスポンス:
[
{
"id": 1,
"title": "牛乳を買う",
"done": false
},
{
"id": 2,
"title": "メールを送る",
"done": true
}
]
特定のタスクを完了にするには、
PATCH /todos/1
{
"done": true
}
レスポンス:
{
"id": 1,
"title": "牛乳を買う",
"done": true
}
このように、「リソースの形（JSON）」と「URL＋メソッド」が揃っていると、API全体が直感的になります。
REST設計で特に大事なポイントを深掘りする
一貫性：同じパターンは同じルールで
REST設計で一番効いてくるのが「一貫性」です。
ユーザーもタスクも、同じパターンで設計します。
GET /users と GET /todos は「一覧を返す」POST /users と POST /todos は「新規作成」GET /users/{id} と GET /todos/{id} は「詳細取得」
こうしておくと、新しいリソースが増えても、クライアント側はすぐに使い方を予想できます。
逆に、
/createUser/getAllTodos/removeTask
のようにバラバラなルールで設計すると、
毎回ドキュメントを見ないと使い方が分からなくなります。
REST設計は、「API全体に共通のパターンを敷く」ことがとても重要です。
ステータスコードで結果を表現する
RESTでは、HTTPステータスコードも大事な「設計の一部」です。
代表的なものだけ押さえておくと十分です。
200 OK
成功（GET / PATCH / DELETE など）
201 Created
新規作成に成功（POST）
400 Bad Request
リクエストが不正（バリデーションエラーなど）
401 Unauthorized
認証が必要
403 Forbidden
権限がない
404 Not Found
リソースが存在しない
500 Internal Server Error
サーバ側の予期しないエラー
例えば、「存在しないタスクを取得しようとしたとき」は、404 Not Found を返します。
GET /todos/9999
レスポンス:
ステータスコード: 404
{
"error": "Todo not found"
}
ステータスコードと JSON のエラーメッセージを組み合わせることで、クライアントは「何が起きたか」を正確に判断できます。
リソースの形（JSON）を安易に変えない
REST設計では、「リソースの表現（JSONの形）」も API の一部です。
例えば、さっきの Todo の JSON を、
{
"id": 1,
"title": "牛乳を買う",
"done": false
}
と決めたなら、安易にキー名を変えたり、構造を変えたりしないことが大事です。
done を is_done に変えるtitle を name に変える
といった変更は、クライアント側のコードを壊します。
どうしても変えたいときは、バージョンを分ける（/v1/todos と /v2/todos）などの工夫が必要になります。
REST設計では、「一度公開したリソースの形は、慎重に扱う」ことが品質に直結します。
Python側のコードとREST設計のつながり
FastAPIやFlaskでRESTっぽく書く
Pythonで REST API を実装するとき、FastAPI を例にするとイメージしやすいです。
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class TodoIn(BaseModel):
title: str
class TodoOut(BaseModel):
id: int
title: str
done: bool
todos: list[TodoOut] = []
next_id = 1
@app.get("/todos", response_model=list[TodoOut])
def list_todos():
return todos
@app.post("/todos", response_model=TodoOut, status_code=201)
def create_todo(todo_in: TodoIn):
global next_id
todo = TodoOut(id=next_id, title=todo_in.title, done=False)
next_id += 1
todos.append(todo)
return todo
ここでも、
URLは名詞（/todos）
メソッドで操作を表現（GET / POST）
JSONの形をモデル（TodoIn, TodoOut）で定義
という REST の考え方がそのまま出てきています。
Python側の設計（ドメインモデル・ユースケース）と REST の設計を揃えると、
API全体が理解しやすく、テストもしやすくなります。
初心者がREST設計でまず意識するといいこと
URLは「名詞」、メソッドは「動詞」として使い分ける
最初の一歩としては、これだけでもかなり違います。
/getUser ではなく /users/{id} にする/createTodo ではなく POST /todos にする
「何をするか」をURLに書くのではなく、
「何に対する操作か」をURLに書き、
「何をするか」は HTTPメソッドで表現する。
このルールを守るだけで、RESTっぽさが一気に出てきます。
同じパターンは同じ形にする
ユーザー、タスク、注文など、リソースが増えても、
一覧取得は GET /xxx
作成は POST /xxx
詳細取得は GET /xxx/{id}
更新は PATCH /xxx/{id}
削除は DELETE /xxx/{id}
というパターンを崩さないようにします。
「新しいリソースを追加するとき、既存のパターンを真似する」
これが REST設計を身につける一番の近道です。
まとめ（REST設計は「リソースとHTTPをきれいに組み合わせる設計」）
初心者目線で整理すると、REST設計はこういうものです。
リソース（ユーザー・タスクなど）を名詞のURLで表し、HTTPメソッド（GET / POST / PATCH / DELETE）で操作を表現することで、API全体に一貫したルールを敷く設計。
ステータスコードやJSONの形も「約束事」として丁寧に決めることで、クライアントから見て予測しやすく・扱いやすいAPIになり、変更にも強くなる。
最初は「URLは名詞」「メソッドは動詞」「同じパターンは同じ形」という3つだけ意識して、小さなTodo APIなどを実際に設計・実装してみると、RESTの感覚がぐっと掴みやすくなる。