結論
REST API とは、Web の仕組み(URL・HTTP のメソッド・ステータスコード)の決まりに沿って、データ(リソース)を取得・作成・更新・削除できるようにした API です。「/tasks/1 に GET を送ると task 1 の JSON が返る」のように、URL が対象を、メソッドが操作を、ステータスコードが結果を表します。
この記事でわかること
- REST の6つの制約(原典の論文)と REST API の意味
- メソッドの安全性・冪等性と、同じ PUT・POST を2回送った結果
- Python 標準ライブラリで作った REST API と curl・requests の実行結果
この記事で実際に動かしたもの:Python 標準ライブラリだけで作った REST API(127.0.0.1)、curl・requests からの GET・POST・PUT・PATCH・DELETE、同じ内容の FastAPI 版。
flowchart TD
C[クライアント<br>curl・requests・アプリ] -->|メソッド + URL| S[REST API サーバー]
S --> R[(リソース<br>例: task 1)]
S -->|ステータスコード + JSON| C
よく調べられることの答えを先にまとめます。
| 知りたいこと | 答え | 詳しい節 |
|---|---|---|
| REST API とは | URL でリソースを指し、HTTP のメソッドで操作する API | REST APIとは |
| REST とは | Roy Fielding が博士論文で示した設計の考え方(6つの制約) | RESTの6つの制約 |
| RESTful API との違い | ほぼ同じ意味で使われる | Web API・RESTful APIとの違い |
| GET・POST・PUT・PATCH・DELETE | 取得・作成・置き換え・一部更新・削除 | HTTPメソッドの意味 |
| 冪等性とは | 同じリクエストを何回送っても結果が1回と同じこと | 冪等性を確かめる |
| ステータスコードの使い分け | 作成は201、本文なしの成功は204、入力の誤りは400・422 | ステータスコードの使い分け |
| Python で作るには | 標準ライブラリの http.server か FastAPI | PythonでREST APIを作る |
| GraphQL・gRPC との違い | エンドポイントの数・データの形式・通信の方式が違う | GraphQL・gRPC・SOAPとの違い |
確認環境:Ubuntu 24.04.5 LTS の上で、Python 3.13.18 の標準ライブラリ(http.server の ThreadingHTTPServer)で小さな REST API を作り、127.0.0.1 のポートで動かしました。呼び出しは curl 8.5.0 の curl -i と、requests 2.34.2(urllib3 2.8.0)です。同じ API を FastAPI 0.163.2(Starlette 1.10.0・Pydantic 2.14.3・uvicorn 0.54.0)でも作り、既定の応答の違いを確かめました。作業場所の venv に入れ、外部のサービス・本物の API には接続していません。REST の定義は Roy Fielding の博士論文の第5章、メソッドとステータスコードの意味は RFC 9110、PATCH は RFC 5789、エラーの本文は RFC 9457、JSON Merge Patch は RFC 7396、Link ヘッダーは RFC 8288、OpenAPI は OpenAPI Specification の公式、GraphQL・gRPC・SOAP(W3C)は各公式の文書で確かめました。図は mermaid で描画を確かめています(確認日 2026年11月18日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「REST APIとは|6つの制約・メソッドの意味とPythonで作る・呼ぶ例」
REST APIとは(意味と仕組みをやさしく)
この節では、REST API の意味と、1回のやり取りで何が起きているのかが分かります。
API(Application Programming Interface)は、プログラム同士がやり取りするための決まりです。「この形で頼めば、この形で返す」という約束で、頼む側(クライアント)は相手の中身を知らなくても使えます。REST API は、その約束を REST という設計の考え方に沿って作った APIで、REST は Representational State Transfer の略です(読み方は「レスト」)。
REST API では、扱うデータをリソースと呼び、1つ1つに URL を付けます。クライアントはその URL に HTTP のメソッドを付けてリクエストを送り、サーバーはステータスコードと、リソースの表現(多くは JSON)を返します。
クライアントがリクエストを送る
メソッド(GET など)・URL(/tasks/1)・ヘッダー(Content-Type など)・必要なら本文(JSON)を送る。
サーバーが URL とメソッドで処理を決める
URL からリソースを、メソッドから操作を読み取り、入力を確かめてからデータを取り出す・作る・変える。
サーバーがステータスコードと表現を返す
結果を3桁のステータスコードで示し、本文にリソースの今の状態を JSON などで入れる。
クライアントが結果を読む
まずステータスコードで成功か失敗かを見て、次に本文とヘッダー(Location・ETag など)を読む。
手元の API に GET を送ったときの応答の実物です(このあとの節で作るサーバーです)。
$ curl --noproxy '*' -s -i http://127.0.0.1:8639/tasks/1
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 55
ETag: "f638f6db1b180e82"
{"id": 1, "title": "請求書を送る", "done": false}
1行目の 200 OK がステータスコード、Content-Type などがヘッダー、最後の JSON が task 1 の表現です。同じ URL に DELETE を送れば削除になり、メソッドを変えるだけで操作が変わります。
REST API の使用例
- 公開されている API:天気・地図・決済などのサービスが、外部のアプリ向けに URL とメソッドを公開している。
- 社内のシステム同士:商品のサービスが在庫のサービスに
GET /products/{id}/stockを送るように、サービスの間をつなぐ。 - 画面とサーバー:ブラウザやスマホのアプリが、画面に出すデータを REST API から取る。
RESTの6つの制約(Fieldingの博士論文 第5章)
この節では、REST の原典が定める6つの制約と、それぞれが REST API のどこに表れるのかが分かります。
REST は、Roy Fielding が2000年の博士論文の第5章で示した、ネットワーク上のハイパーメディアの仕組みのための「設計の考え方(アーキテクチャスタイル)」です。決まった規格やライブラリではなく、いくつかの制約を足し合わせて導かれます。論文は「名前を付けられる情報は、どれもリソースになりうる」(Any information that can be named can be a resource)と述べています(5.2.1.1)。
| 制約(論文の節) | 意味 | REST API での表れ方 |
|---|---|---|
| クライアント・サーバー(5.1.2) | 画面の側とデータの側を分ける(関心の分離) | 画面とサーバーを別々に作って入れ替えられる |
| ステートレス(5.1.3) | 1つのリクエストに、理解に必要な情報をすべて含める | サーバーは前のリクエストを覚えておかない。ページの位置も URL で送る |
| キャッシュ(5.1.4) | 応答に「キャッシュしてよいか」を示す | Cache-Control・ETag と 304 Not Modified |
| 統一インターフェース(5.1.5) | どのリソースも同じやり方で扱う | URL・決まったメソッド・Content-Type・リンク |
| 階層化システム(5.1.6) | 間に層(中継・キャッシュ・負荷分散)を挟める | クライアントはロードバランサーや CDN の存在を知らなくてよい |
| コードオンデマンド(5.1.7・任意) | サーバーから実行できるコードを送って機能を足せる | ブラウザに JavaScript を送る形。REST API ではあまり使わない |
コードオンデマンドは、論文でも「任意の制約」(only an optional constraint)とされています。
統一インターフェースの4つの制約
統一インターフェースは、論文でさらに4つに分けられています(5.1.5)。
1リソースの識別
リソースを URL で指す。/tasks/1 は「task 1」というリソースの名前で、中身の保存方法とは別のもの。
2表現によるリソースの操作
クライアントは JSON などの表現を受け取り、表現を送り返して変える。データベースの行を直接さわるわけではない。
3自己記述的なメッセージ
メッセージだけで読み方が分かる。Content-Type: application/json やステータスコードがその役割をする。
4アプリケーション状態のエンジンとしてのハイパーメディア
次にできる操作をリンクで示す(HATEOAS と呼ばれる)。この記事の API では Link ヘッダーの next がその例。
論文では、表現は「バイトの並びと、それを説明するメタデータ」(a sequence of bytes, plus representation metadata)と定義されています(5.2.1.2)。サーバーの中でデータベースに保存していても、送るのは JSON という「表現」だ、という考え方です。
RESTの名前の意味
Representational State Transfer は「表現(Representation)によって状態(State)を移す(Transfer)」という意味です。クライアントは、リソースの今の状態を表現として受け取り、新しい状態を表現として送ります。
REST APIとWeb API・RESTful APIの違い
この節では、似た言葉(Web API・RESTful API・HTTP API)との違いが分かります。
| 言葉 | 意味 | 関係 |
|---|---|---|
| API | プログラム同士のやり取りの決まり全般 | いちばん広い |
| Web API | HTTP など Web の仕組みで呼ぶ API | REST・GraphQL・SOAP などを含む |
| REST API | REST の考え方に沿った Web API | Web API の一種 |
| RESTful API | REST の考え方に沿った API | REST API とほぼ同じ意味で使われる |
| HTTP API・JSON API | HTTP で JSON を返す API | 6つの制約をすべて満たすとは限らない |
AWS の解説も、REST API と RESTful API は同じ意味で使えると説明しています。実際の開発では「URL でリソースを指し、メソッドで操作し、JSON を返す API」をまとめて REST API と呼ぶことが多く、統一インターフェースのリンク(HATEOAS)まで備えた API は多くありません。
REST API のよい点と、向かない点
よい点
HTTP を話せる言語・ツールならどれからでも呼べる(curl だけで試せる)
URL とメソッドが決まっているので読みやすい
ステートレスなので、サーバーを増やして負荷を分けやすい
HTTP のキャッシュ・中継の仕組みをそのまま使える
向かない点
1画面に多くのリソースが要ると、リクエストの回数が増える
返す項目がサーバーで決まり、要らない項目まで届くことがある
型の定義は別に書く(OpenAPI など)
双方向・連続の通信は別の方式(WebSocket など)を組み合わせる
REST APIのURLの決まり(リソース・ページング・バージョン)
この節では、REST API の URL の付け方と、一覧の分け方(ページング)・バージョンの付け方の基本が分かります。
URL はリソースの名前なので、名詞で付け、操作はメソッドで表します。一覧(コレクション)は複数形、1件は「複数形/ID」が広く使われる形です。
URL に操作を入れるか、メソッドで表すか
見分ける問い:「URL を読んだだけで何が起きるか決まってしまうか」
| やりたいこと | メソッドと URL | 成功のときの応答 |
|---|---|---|
| 一覧を取る | GET /tasks | 200 と一覧の JSON |
| 1件を取る | GET /tasks/1 | 200 と1件の JSON |
| 新しく作る(ID はサーバーが決める) | POST /tasks | 201 と Location: /tasks/{新しいID} |
| 丸ごと置き換える(ID を指定) | PUT /tasks/1 | 200 または 204(無ければ作って201) |
| 一部だけ変える | PATCH /tasks/1 | 200 と変えたあとの JSON |
| 削除する | DELETE /tasks/1 | 204(本文なし) |
| 子のリソース | GET /projects/3/tasks | 200 と project 3 の task の一覧 |
ページング(一覧を分けて返す)
一覧が大きいときは、クエリ(?limit=2&offset=0)で区切って返します。ステートレスの制約どおり、「今どこまで読んだか」はサーバーが覚えずに、クライアントが毎回 URL で送ります。手元の API では、次のページの URL を Link ヘッダー(RFC 8288)の rel="next" で返しました。requests はこれを r.links で辞書として読めます。
Link: </tasks?limit=2&offset=2>; rel="next"
r.links: {'next': {'url': '/tasks?limit=2&offset=2', 'rel': 'next'}}
total 5 items [1, 2]
次のページを URL として渡しておくと、クライアントは URL を組み立てずにリンクをたどれます。統一インターフェースの「ハイパーメディア」を小さく取り入れた形です。
バージョン
互換性の無い変更を入れるときは、/v1/tasks のように URL に版を入れる方法、クエリやヘッダーで渡す方法があります。どの方法も、使っている側が移るまで前の版を残す運用とセットです。URL・ページング(オフセットとカーソル)・バージョンの決め方を比べた詳しい設計は、関連記事「REST APIの設計|URL・ステータスコード・エラー形式の決め方」で扱っています。
HTTPメソッドの意味(GET・POST・PUT・PATCH・DELETE)と安全性・冪等性
この節では、REST API で使う HTTP メソッドの意味と、「安全」「冪等」という2つの性質が分かります。
RFC 9110 は、GET・HEAD・OPTIONS・TRACE を「安全」(サーバーの状態を変えない)、PUT・DELETE と安全なメソッドを「冪等」と定めています(9.2.1・9.2.2)。冪等(べきとう)とは、同じリクエストを何回送っても、サーバーへの意図した効果が1回送ったときと同じになることです。PATCH は RFC 5789 で「安全でも冪等でもない」とされています。
| メソッド | 意味 | 安全 | 冪等 | 手元で2回送った結果 |
|---|---|---|---|---|
| GET | 取得 | ○ | ○ | 200・200(何も変わらない) |
| HEAD | ヘッダーだけ取得 | ○ | ○ | 200(本文なし) |
| OPTIONS | 使えるメソッドを聞く | ○ | ○ | 204 と Allow ヘッダー |
| POST | 作成・処理の依頼 | × | × | 201・201(2件できた) |
| PUT | 丸ごと置き換え(無ければ作成) | × | ○ | 201・200(1件のまま) |
| PATCH | 一部の更新 | × | ×(作り方による) | 200・200(merge patch なので同じ状態) |
| DELETE | 削除 | × | ○ | 204・404(状態は同じ「無い」) |
DELETE の2回目は404でしたが、冪等は「応答が同じ」ではなく「サーバーの状態への効果が同じ」という意味なので、冪等の決まりには反しません。2回目も「task が無い」状態は変わりません。
PUT と PATCH の違い、POST と PUT の違い
- PUT は丸ごと置き換え:送った表現がそのままリソースの新しい状態になる。送らなかった項目は残らない。
- PATCH は差分の適用:送った項目だけ変える。差分の書き方(形式)を Content-Type で示す。手元では JSON Merge Patch(RFC 7396、
application/merge-patch+json)にした。 - POST はサーバーが ID を決める作成:URL はコレクション(/tasks)。RFC 9110 は、作成したときは201と Location ヘッダーを返すことを勧めている(9.3.3)。
- PUT はクライアントが URL を決める:無ければ作って201、あれば置き換えて200か204(9.3.4)。
REST APIのステータスコードの使い分け
この節では、REST API でよく使うステータスコードと、どれを返すかの決め方が分かります。
ステータスコードは「結果の種類」を3桁で伝えます。2xx は成功、4xx はクライアント側の問題、5xx はサーバー側の問題です。本文に「success: false」と書いて200を返すより、コードで結果を表すほうが、クライアント・中継・ログのすべてで扱いやすくなります。
| コード | 意味(RFC 9110) | REST API で返す場面 |
|---|---|---|
| 200 OK | 成功 | GET・PUT・PATCH で本文を返すとき |
| 201 Created | 作成した | POST で作成・PUT で新しく作成。Location を付ける |
| 204 No Content | 成功・本文なし | DELETE・本文を返さない更新 |
| 304 Not Modified | 変わっていない | If-None-Match の ETag が今と同じとき |
| 400 Bad Request | リクエストを処理できない | JSON として読めない |
| 404 Not Found | 今の表現が見つからない | その ID のリソースが無い |
| 405 Method Not Allowed | そのメソッドは使えない | DELETE /tasks など。Allow ヘッダーが必須(15.5.6) |
| 409 Conflict | 今の状態とぶつかる | 同じ名前がすでにある・状態の遷移が合わない |
| 412 Precondition Failed | 前提の条件が合わない | If-Match の ETag が今のものと違う(先に別の更新が入った) |
| 415 Unsupported Media Type | その形式は受け付けない | Content-Type が違う |
| 422 Unprocessable Content | 形式は分かるが内容を処理できない | 必須の項目が空・文字数が範囲外 |
認証・権限の 401・403 もよく使いますが、この記事では扱いません。どのコードを返すか迷ったときは、次の順に確かめると決めやすくなります。
- 1その URL にそのメソッドは使えるか → 使えなければ 405Allow ヘッダーで使えるメソッドを返す
- 2Content-Type は受け付ける形式か → 違えば 415PATCH なら Accept-Patch を付ける
- 3本文は JSON として読めるか → 読めなければ 400括弧や引用符の誤り
- 4リソースはあるか → 無ければ 404PUT は無ければ作成してよい
- 5項目の内容は決まりに合うか → 合わなければ 422どの項目かを本文で返す
- 6前提の条件・今の状態とぶつからないか → 412・409If-Match の ETag・重複
- 7成功 → 200・201・204作成は201と Location、本文なしは204
すべてのステータスコードの意味と curl での見え方は、関連記事「HTTPステータスコード 一覧|全コードの原因と対処・curl実例つき」で扱っています。
PythonでREST APIを作る(標準ライブラリだけ・127.0.0.1)
この節では、外部のライブラリを使わずに、Python だけで REST API を作るコードが分かります。
次のコードは、task(作業)を GET・POST・PUT・PATCH・DELETE・OPTIONS で扱う REST API です。データはメモリーに置き、エラーは RFC 9457 の形(application/problem+json)で返します。python3 server.py で 127.0.0.1:8639 に立ち上がります(Python 3.13.18 で動かしたコードをそのまま載せています)。
import json, re, hashlib, threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import urlsplit, parse_qs
TASKS = {} # id -> dict
NEXT_ID = [1]
LOCK = threading.Lock()
PROBLEM = "application/problem+json"
def etag(task):
raw = json.dumps(task, sort_keys=True, ensure_ascii=False).encode()
return '"' + hashlib.sha256(raw).hexdigest()[:16] + '"'
def validate(body, partial=False):
errors = []
if not partial or "title" in body:
t = body.get("title")
if not isinstance(t, str) or not (1 <= len(t) <= 100):
errors.append({"pointer": "#/title", "detail": "1〜100文字の文字列"})
if "done" in body and not isinstance(body["done"], bool):
errors.append({"pointer": "#/done", "detail": "true か false"})
return errors
class Handler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"
server_version = "tasks-api/1.0"
def log_message(self, *a):
pass
def send(self, status, body=None, ctype="application/json", headers=None):
data = b"" if body is None else json.dumps(body, ensure_ascii=False).encode()
self.send_response(status)
if body is not None:
self.send_header("Content-Type", ctype)
self.send_header("Content-Length", str(len(data)))
for k, v in (headers or {}).items():
self.send_header(k, v)
self.end_headers()
if self.command != "HEAD":
self.wfile.write(data)
def problem(self, status, title, detail, headers=None, **extra):
body = {"type": "about:blank", "title": title, "status": status,
"detail": detail, "instance": self.path, **extra}
self.send(status, body, PROBLEM, headers)
def read_json(self, allowed):
ctype = (self.headers.get("Content-Type") or "").split(";")[0].strip()
length = int(self.headers.get("Content-Length") or 0)
raw = self.rfile.read(length)
if ctype not in allowed:
h = {"Accept-Patch": allowed[0]} if self.command == "PATCH" else None
self.problem(415, "Unsupported Media Type",
f"Content-Type は {', '.join(allowed)} で送る", headers=h)
return None
try:
return json.loads(raw or b"null")
except json.JSONDecodeError as e:
self.problem(400, "Bad Request", f"JSON として読めない: {e.msg}")
return None
def route(self):
path = urlsplit(self.path).path
if path == "/tasks":
return "collection", None
m = re.fullmatch(r"/tasks/(\d+)", path)
if m:
return "item", int(m.group(1))
return None, None
def not_allowed(self, allow):
self.send_response(405)
body = json.dumps({"type": "about:blank", "title": "Method Not Allowed",
"status": 405, "detail": f"{self.command} は使えない"},
ensure_ascii=False).encode()
self.send_header("Allow", allow)
self.send_header("Content-Type", PROBLEM)
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
# ---- methods ----
def do_GET(self):
kind, tid = self.route()
if kind == "collection":
q = parse_qs(urlsplit(self.path).query)
limit = min(int(q.get("limit", ["10"])[0]), 100)
offset = int(q.get("offset", ["0"])[0])
items = sorted(TASKS.values(), key=lambda t: t["id"])
page = items[offset:offset + limit]
links = []
if offset + limit < len(items):
links.append(f'</tasks?limit={limit}&offset={offset+limit}>; rel="next"')
if offset > 0:
links.append(f'</tasks?limit={limit}&offset={max(0, offset-limit)}>; rel="prev"')
h = {"Link": ", ".join(links)} if links else {}
return self.send(200, {"items": page, "total": len(items),
"limit": limit, "offset": offset}, headers=h)
if kind == "item":
t = TASKS.get(tid)
if not t:
return self.problem(404, "Not Found", f"task {tid} は無い")
tag = etag(t)
if self.headers.get("If-None-Match") == tag:
self.send_response(304); self.send_header("ETag", tag)
self.send_header("Content-Length", "0"); self.end_headers(); return
return self.send(200, t, headers={"ETag": tag})
self.problem(404, "Not Found", "そのURLのリソースは無い")
do_HEAD = do_GET
def do_POST(self):
kind, _ = self.route()
if kind == "item":
return self.not_allowed("GET, HEAD, PUT, PATCH, DELETE")
if kind != "collection":
return self.problem(404, "Not Found", "そのURLのリソースは無い")
body = self.read_json(["application/json"])
if body is None:
return
errs = validate(body)
if errs:
return self.problem(422, "Unprocessable Content", "入力に誤りがある", errors=errs)
with LOCK:
tid = NEXT_ID[0]; NEXT_ID[0] += 1
TASKS[tid] = {"id": tid, "title": body["title"], "done": body.get("done", False)}
t = TASKS[tid]
self.send(201, t, headers={"Location": f"/tasks/{tid}", "ETag": etag(t)})
def do_PUT(self):
kind, tid = self.route()
if kind == "collection":
return self.not_allowed("GET, HEAD, POST")
if kind != "item":
return self.problem(404, "Not Found", "そのURLのリソースは無い")
body = self.read_json(["application/json"])
if body is None:
return
errs = validate(body)
if errs:
return self.problem(422, "Unprocessable Content", "入力に誤りがある", errors=errs)
with LOCK:
cur = TASKS.get(tid)
if cur and self.headers.get("If-Match") not in (None, etag(cur)):
return self.problem(412, "Precondition Failed", "先に別の更新が入った")
created = cur is None
TASKS[tid] = {"id": tid, "title": body["title"], "done": body.get("done", False)}
NEXT_ID[0] = max(NEXT_ID[0], tid + 1)
t = TASKS[tid]
h = {"ETag": etag(t)}
if created:
h["Location"] = f"/tasks/{tid}"
self.send(201 if created else 200, t, headers=h)
def do_PATCH(self):
kind, tid = self.route()
if kind != "item":
return self.not_allowed("GET, HEAD, POST")
body = self.read_json(["application/merge-patch+json"])
if body is None:
return
with LOCK:
cur = TASKS.get(tid)
if not cur:
return self.problem(404, "Not Found", f"task {tid} は無い")
errs = validate(body, partial=True)
if errs:
return self.problem(422, "Unprocessable Content", "入力に誤りがある", errors=errs)
if self.headers.get("If-Match") not in (None, etag(cur)):
return self.problem(412, "Precondition Failed", "先に別の更新が入った")
for k in ("title", "done"):
if k in body:
cur[k] = body[k]
self.send(200, cur, headers={"ETag": etag(cur)})
def do_DELETE(self):
kind, tid = self.route()
if kind == "collection":
return self.not_allowed("GET, HEAD, POST")
with LOCK:
if TASKS.pop(tid, None) is None:
return self.problem(404, "Not Found", f"task {tid} は無い")
self.send(204)
def do_OPTIONS(self):
kind, _ = self.route()
allow = "GET, HEAD, POST, OPTIONS" if kind == "collection" else \
"GET, HEAD, PUT, PATCH, DELETE, OPTIONS"
self.send(204, headers={"Allow": allow, "Accept-Patch": "application/merge-patch+json"})
if __name__ == "__main__":
import sys
port = int(sys.argv[1]) if len(sys.argv) > 1 else 8639
ThreadingHTTPServer(("127.0.0.1", port), Handler).serve_forever()
コードの要点は次のとおりです。
- ルーティング:
route()で URL を「コレクション(/tasks)」と「1件(/tasks/数字)」に分け、do_GETなどのメソッドごとの関数で操作を分ける。 - 作成:POST は ID を決めて201と
Location、PUT は無ければ201、あれば200。 - 条件付きリクエスト:内容から
ETagを作り、If-None-Matchが同じなら304、If-Matchが違えば412。 - エラー:405 には
Allow、PATCH の415にはAccept-Patchを付ける。 - keep-alive:
protocol_version = "HTTP/1.1"で接続を使い回せるようにした(この設定だけだと遅くなる点は、あとの requests の節で実測しています)。
同じ API を Java の Spring Boot で作る手順は、関連記事「Spring BootでREST APIを作る|入力チェック・エラー処理・テストまで」で扱っています。
curlでREST APIを呼ぶ(GET・POST・PUT・PATCH・DELETEの実行結果)
この節では、curl で REST API を呼んだときに、ステータスコードとヘッダーがどう返るのかが実物で分かります。
curl は -X でメソッド、-H でヘッダー、-d で本文を指定し、-i で応答のヘッダーまで表示します。上のサーバーに順に送った結果です(Server・Date の行は省いています)。
POST で作る(201 Created と Location)
$ curl --noproxy '*' -s -i -X POST http://127.0.0.1:8639/tasks -H 'Content-Type: application/json' -d '{"title":"請求書を送る"}'
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 55
Location: /tasks/1
ETag: "f638f6db1b180e82"
{"id": 1, "title": "請求書を送る", "done": false}
PUT で置き換える(200 OK)
$ curl --noproxy '*' -s -i -X PUT http://127.0.0.1:8639/tasks/1 -H 'Content-Type: application/json' -d '{"title":"請求書を送る","done":true}'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 54
ETag: "698e34be7343cd93"
{"id": 1, "title": "請求書を送る", "done": true}
PATCH で一部だけ変える(200 OK)
$ curl --noproxy '*' -s -i -X PATCH http://127.0.0.1:8639/tasks/1 -H 'Content-Type: application/merge-patch+json' -d '{"title":"請求書を再送する"}'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 60
ETag: "62efbb4fdd1c0307"
{"id": 1, "title": "請求書を再送する", "done": true}
DELETE で削除する(204 No Content、2回目は404)
$ curl --noproxy '*' -s -i -X DELETE http://127.0.0.1:8639/tasks/1
HTTP/1.1 204 No Content
Content-Length: 0
$ curl --noproxy '*' -s -i -X DELETE http://127.0.0.1:8639/tasks/1
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Content-Length: 114
{"type": "about:blank", "title": "Not Found", "status": 404, "detail": "task 1 は無い", "instance": "/tasks/1"}
HEAD と OPTIONS
$ curl --noproxy '*' -s -I http://127.0.0.1:8639/tasks/2
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 64
ETag: "3f7d65d9ff301c1c"
$ curl --noproxy '*' -s -i -X OPTIONS http://127.0.0.1:8639/tasks/2
HTTP/1.1 204 No Content
Content-Length: 0
Allow: GET, HEAD, PUT, PATCH, DELETE, OPTIONS
Accept-Patch: application/merge-patch+json
HEAD は GET と同じヘッダー(Content-Length 64・ETag)を返し、本文は返しませんでした。OPTIONS は、その URL で使えるメソッドを Allow で返しています。
| curl のオプション | 働き | 例 |
|---|---|---|
-X |
メソッドを指定 | -X DELETE |
-H |
ヘッダーを足す | -H 'Content-Type: application/json' |
-d |
本文を送る(-X が無ければ POST になる) | -d '{"title":"…"}' |
-i |
応答のヘッダーも表示 | ステータスと Location を見る |
-I |
HEAD を送る | ヘッダーだけ確かめる |
冪等性を確かめる:同じPUTとPOSTを2回送った結果
この節では、「冪等」の違いが、同じリクエストを2回送ったときのリソースの件数でどう表れるのかが分かります。
同じ POST を2回送ると task が2件でき、同じ PUT を2回送っても1件のままでした。次のコードで、送るたびに一覧の件数(total)を数えています。
import requests
BASE = "http://127.0.0.1:8639"
s = requests.Session()
s.trust_env = False # プロキシの環境変数を使わない
def count():
return s.get(f"{BASE}/tasks", params={"limit": 100}, timeout=5).json()["total"]
print("最初の件数:", count())
# 同じ POST を2回
body = {"title": "見積書を作る"}
for i in range(2):
r = s.post(f"{BASE}/tasks", json=body, timeout=5)
print(f"POST {i+1}回目:", r.status_code, r.headers["Location"], "件数", count())
# 同じ PUT を2回
body = {"title": "議事録を共有する", "done": False}
for i in range(2):
r = s.put(f"{BASE}/tasks/100", json=body, timeout=5)
print(f"PUT {i+1}回目:", r.status_code, r.json(), "件数", count())
# 同じ PATCH を2回(merge patch)
for i in range(2):
r = s.patch(f"{BASE}/tasks/100", data='{"done": true}',
headers={"Content-Type": "application/merge-patch+json"}, timeout=5)
print(f"PATCH {i+1}回目:", r.status_code, r.json())
# 同じ DELETE を2回
for i in range(2):
r = s.delete(f"{BASE}/tasks/100", timeout=5)
print(f"DELETE {i+1}回目:", r.status_code, "件数", count())
最初の件数: 0
POST 1回目: 201 /tasks/1 件数 1
POST 2回目: 201 /tasks/2 件数 2
PUT 1回目: 201 {'id': 100, 'title': '議事録を共有する', 'done': False} 件数 3
PUT 2回目: 200 {'id': 100, 'title': '議事録を共有する', 'done': False} 件数 3
PATCH 1回目: 200 {'id': 100, 'title': '議事録を共有する', 'done': True}
PATCH 2回目: 200 {'id': 100, 'title': '議事録を共有する', 'done': True}
DELETE 1回目: 204 件数 2
DELETE 2回目: 404 件数 2
通信が途中で切れて「届いたか分からない」とき、PUT・DELETE は送り直しても結果が変わりません。POST は送り直すと二重に作られることがあるため、送り直す前に一覧で確かめるか、サーバー側で同じ依頼を見分ける仕組み(冪等キー)を用意します。冪等キーは、クライアントが依頼ごとに一意の値をヘッダーで送り、サーバーが同じ値の2回目を「作成済み」として扱う仕組みです。
PythonのrequestsでREST APIを呼ぶ(再試行・ETag・接続の使い回し)
この節では、Python の requests で REST API を呼ぶときの書き方と、再試行・条件付きリクエスト・接続の使い回しの実測が分かります。
requests では s.get()・s.post(json=...) のようにメソッド名の関数を呼び、必ず timeout を付けます。json= に辞書を渡すと、JSON に変換して Content-Type: application/json を付けて送ります。
# 条件付きリクエスト
r = s.get(f"{BASE}/tasks/2", timeout=5)
tag = r.headers["ETag"]
r2 = s.get(f"{BASE}/tasks/2", headers={"If-None-Match": tag}, timeout=5)
print("If-None-Match:", r2.status_code, "本文の長さ", len(r2.content))
s.patch(f"{BASE}/tasks/2", data='{"title": "見積書を作る(改)"}',
headers={"Content-Type": "application/merge-patch+json"}, timeout=5)
r3 = s.put(f"{BASE}/tasks/2", json={"title": "見積書を作る", "done": True},
headers={"If-Match": tag}, timeout=5)
print("前の ETag で If-Match:", r3.status_code, r3.headers["Content-Type"], r3.json()["detail"])
# エラーを例外にする
try:
s.get(f"{BASE}/tasks/999", timeout=5).raise_for_status()
except requests.HTTPError as e:
print("raise_for_status:", e)
# ページング
for i in range(3):
s.post(f"{BASE}/tasks", json={"title": f"作業{i}"}, timeout=5)
r = s.get(f"{BASE}/tasks", params={"limit": 2, "offset": 0}, timeout=5)
print("Link:", r.headers.get("Link"))
print("r.links:", r.links)
print("total", r.json()["total"], "items", [t["id"] for t in r.json()["items"]])
If-None-Match: 304 本文の長さ 0
前の ETag で If-Match: 412 application/problem+json 先に別の更新が入った
raise_for_status: 404 Client Error: Not Found for url: http://127.0.0.1:8639/tasks/999
Link: </tasks?limit=2&offset=2>; rel="next"
r.links: {'next': {'url': '/tasks?limit=2&offset=2', 'rel': 'next'}}
total 5 items [1, 2]
304 のときは本文が0バイトで、手元に持っている表現をそのまま使えます。412 は「取得したあとに別の更新が入った」ことを示し、上書きを防げます。
再試行してよいのは冪等なメソッドだけ
urllib3(requests の下で動くライブラリ)の再試行の設定 Retry は、既定で冪等なメソッドだけを再試行します。最初の2回は503を返し、3回目に200を返すサーバーを 127.0.0.1 に立てて確かめました。
import requests, urllib3
from urllib3.util.retry import Retry
from requests.adapters import HTTPAdapter
print("urllib3", urllib3.__version__)
print("既定で再試行するメソッド:", sorted(Retry.DEFAULT_ALLOWED_METHODS))
s = requests.Session(); s.trust_env = False
s.mount("http://", HTTPAdapter(max_retries=Retry(total=3, backoff_factor=0.1, status_forcelist=[503], raise_on_status=False)))
for m in ("PUT", "POST"):
r = s.request(m, "http://127.0.0.1:8640/x", json={"a": 1}, timeout=5)
print(m, "最終のステータス:", r.status_code)
print("サーバーが受けた回数:", requests.get("http://127.0.0.1:8640/hits", proxies={"http": None}, timeout=5).text)
urllib3 2.8.0
既定で再試行するメソッド: ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE']
PUT 最終のステータス: 200
POST 最終のステータス: 503
サーバーが受けた回数: {'PUT': 3, 'POST': 1, 'GET': 1}
PUT は3回送られて200になり、POST は1回だけで503のまま終わりました。POST も再試行したいときは、allowed_methods に POST を足す前に、サーバー側で二重に作られない仕組みを用意しておきます。
接続の使い回し(Session)の実測
requests.get() を毎回呼ぶと、そのたびに TCP の接続を作ります。Session は接続を使い回します。50件の GET を3回ずつ送った中央値です。
| サーバーの設定 | requests.get を毎回 | Session を使い回し |
|---|---|---|
| HTTP/1.1 のみ(上のコードのまま) | 2.73 ms/件 | 43.44 ms/件 |
HTTP/1.1 + disable_nagle_algorithm = True |
1.25 ms/件 | 0.71 ms/件 |
http.server で keep-alive にしたまま使い回すと、1件40ms台に遅くなりました。ヘッダーと本文を別々に書き出すため、TCP の送信をまとめる仕組み(Nagle アルゴリズム)と相手の確認応答の待ち時間が重なったと考えられます。ハンドラーのクラスに disable_nagle_algorithm = True(socketserver の StreamRequestHandler のクラス属性。公式の文書には記載が無く、ソースコードで確かめました)を足すと、Session のほうが速くなりました。標準ライブラリで試作するときの注意点です。
エラーの返し方(RFC 9457 Problem Details)とFastAPIの既定の応答
この節では、REST API のエラーの本文の書き方と、手元で返したエラーの実物、FastAPI の既定の形との違いが分かります。
RFC 9457 は、HTTP API のエラーを application/problem+json で返す形を定めています。決まった項目は type・title・status・detail・instance の5つで、type が無いときは about:blank(ステータスコード以上の意味を持たない)とみなします。項目は足してよく、手元では入力の誤りを errors に入れました。
| 項目 | 意味 | 手元の例 |
|---|---|---|
| type | 問題の種類を示す URI | about:blank |
| title | 種類の短い説明(毎回同じ) | Unprocessable Content |
| status | ステータスコード(応答と同じ値) | 422 |
| detail | 今回の問題の説明 | 入力に誤りがある |
| instance | 今回の問題を指す URI | /tasks |
手元の API が返したエラー
$ curl --noproxy '*' -s -i -X POST http://127.0.0.1:8639/tasks -H 'Content-Type: application/json' -d '{"title":""}'
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Length: 207
{"type": "about:blank", "title": "Unprocessable Content", "status": 422, "detail": "入力に誤りがある", "instance": "/tasks", "errors": [{"pointer": "#/title", "detail": "1〜100文字の文字列"}]}
$ curl --noproxy '*' -s -i -X POST http://127.0.0.1:8639/tasks -H 'Content-Type: application/json' -d '{title:1}'
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 175
{"type": "about:blank", "title": "Bad Request", "status": 400, "detail": "JSON として読めない: Expecting property name enclosed in double quotes", "instance": "/tasks"}
$ curl --noproxy '*' -s -i -X POST http://127.0.0.1:8639/tasks -H 'Content-Type: text/plain' -d 'hello'
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json
Content-Length: 152
{"type": "about:blank", "title": "Unsupported Media Type", "status": 415, "detail": "Content-Type は application/json で送る", "instance": "/tasks"}
$ curl --noproxy '*' -s -i -X DELETE http://127.0.0.1:8639/tasks
HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD, POST
Content-Type: application/problem+json
Content-Length: 105
{"type": "about:blank", "title": "Method Not Allowed", "status": 405, "detail": "DELETE は使えない"}
$ curl --noproxy '*' -s -i -X PATCH http://127.0.0.1:8639/tasks/2 -H 'Content-Type: application/json' -d '{"done":true}'
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json
Content-Length: 166
Accept-Patch: application/merge-patch+json
{"type": "about:blank", "title": "Unsupported Media Type", "status": 415, "detail": "Content-Type は application/merge-patch+json で送る", "instance": "/tasks/2"}
FastAPI で同じ API を作った場合
FastAPI は、型を書くだけで入力の確かめと OpenAPI の定義を作ります。同じ task の API を FastAPI で作ったコードです(uvicorn fast_app:app --host 127.0.0.1 --port 8642 で起動)。
from fastapi import FastAPI, HTTPException, Response
from pydantic import BaseModel, Field
app = FastAPI(title="tasks-api", version="1.0.0")
TASKS: dict[int, dict] = {}
class TaskIn(BaseModel):
title: str = Field(min_length=1, max_length=100)
done: bool = False
class Task(TaskIn):
id: int
@app.get("/tasks")
def list_tasks(limit: int = 10, offset: int = 0) -> dict:
items = sorted(TASKS.values(), key=lambda t: t["id"])
return {"items": items[offset:offset + limit], "total": len(items)}
@app.post("/tasks", status_code=201)
def create_task(body: TaskIn, response: Response) -> Task:
tid = max(TASKS, default=0) + 1
TASKS[tid] = {"id": tid, **body.model_dump()}
response.headers["Location"] = f"/tasks/{tid}"
return TASKS[tid]
@app.get("/tasks/{tid}")
def get_task(tid: int) -> Task:
if tid not in TASKS:
raise HTTPException(status_code=404, detail=f"task {tid} は無い")
return TASKS[tid]
@app.put("/tasks/{tid}")
def put_task(tid: int, body: TaskIn, response: Response) -> Task:
if tid not in TASKS:
response.status_code = 201
TASKS[tid] = {"id": tid, **body.model_dump()}
return TASKS[tid]
@app.delete("/tasks/{tid}", status_code=204)
def delete_task(tid: int) -> None:
if TASKS.pop(tid, None) is None:
raise HTTPException(status_code=404, detail=f"task {tid} は無い")
# わざと status_code を付けない POST(既定の 200 になる)
@app.post("/notes")
def create_note(body: TaskIn) -> dict:
return {"id": 1, **body.model_dump()}
送った結果のうち、標準ライブラリ版と違ったものです。
$ curl -i -X POST http://127.0.0.1:8642/tasks -H 'Content-Type: application/json' -d '{"title":""}'
HTTP/1.1 422 Unprocessable Content
content-length: 145
content-type: application/json
{"detail":[{"type":"string_too_short","loc":["body","title"],"msg":"String should have at least 1 character","input":"","ctx":{"min_length":1}}]}
$ curl -i -X POST http://127.0.0.1:8642/tasks -H 'Content-Type: text/plain' -d 'hello'
HTTP/1.1 422 Unprocessable Content
content-length: 152
content-type: application/json
{"detail":[{"type":"model_attributes_type","loc":["body"],"msg":"Input should be a valid dictionary or object to extract fields from","input":"hello"}]}
$ curl -i -X POST http://127.0.0.1:8642/notes -H 'Content-Type: application/json' -d '{"title":"メモ"}'
HTTP/1.1 200 OK
content-length: 38
content-type: application/json
{"id":1,"title":"メモ","done":false}
$ curl -i -X DELETE http://127.0.0.1:8642/tasks
HTTP/1.1 405 Method Not Allowed
allow: GET
content-length: 31
content-type: application/json
{"detail":"Method Not Allowed"}
| 場面 | 標準ライブラリ版(自作) | FastAPI 0.163.2 の既定 |
|---|---|---|
| 入力の誤り | 422・problem+json | 422・application/json の {"detail":[…]} |
| Content-Type が text/plain | 415 | 422(本文を辞書として読めない) |
| POST の成功 | 201(自分で指定) | status_code=201 を書かないと200 |
| 使えないメソッド | 405・Allow: GET, HEAD, POST | 405・Allow: GET(POST も受け付けるが Allow に出なかった) |
| ID が数字でない | 404 | 422(int_parsing) |
どちらがよいというより、フレームワークの既定の応答を、自分の API の決まりと合わせて確かめることが大切です。FastAPI でも、入力の誤りの例外(RequestValidationError)のハンドラーを足すと、problem+json で返せました。
# 入力の誤りを problem+json で返す例
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi import Request
@app.exception_handler(RequestValidationError)
async def problem_handler(request: Request, exc: RequestValidationError):
return JSONResponse(
status_code=422, media_type="application/problem+json",
content={"type": "about:blank", "title": "Unprocessable Content",
"status": 422, "detail": "入力に誤りがある",
"instance": request.url.path,
"errors": [{"loc": e["loc"], "msg": e["msg"]} for e in exc.errors()]})
$ curl -i -X POST http://127.0.0.1:8642/tasks -H 'Content-Type: application/json' -d '{"title":""}'
HTTP/1.1 422 Unprocessable Content
content-length: 207
content-type: application/problem+json
{"type":"about:blank","title":"Unprocessable Content","status":422,"detail":"入力に誤りがある","instance":"/tasks","errors":[{"loc":["body","title"],"msg":"String should have at least 1 character"}]}
OpenAPIとREST API・GraphQL・gRPC・SOAPとの違い
この節では、REST API と OpenAPI の関係と、ほかの API の方式との違い、どれを選ぶかの判断が分かります。
OpenAPI は REST API の「仕様書の書き方」の標準で、REST API そのものではありません。OpenAPI Specification は、HTTP API の言語に依存しない標準のインターフェースを定めるもので、2026年11月18日時点の最新版は 3.2.1 です。FastAPI 0.163.2 は、手元の task の API から OpenAPI 3.1.0 の定義を自動で作りました。
openapi 3.1.0
['/tasks', '/tasks/{tid}', '/notes']
{"201": {"description": "Successful Response", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Task"}}}}, "422": {"description": "Validation Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}}}}
POST /tasks の応答に 201 と 422 の両方が書かれ、Swagger UI などのツールで画面に出したり、クライアントのコードを作ったりできます。YAML での書き方とチームでの運用は、関連記事「OpenAPIの書き方|YAMLのテンプレートとチームで使う運用」で扱っています。
| REST API | GraphQL | gRPC | SOAP | |
|---|---|---|---|---|
| 考え方 | リソースを URL で指しメソッドで操作 | API 向けの問い合わせ言語 | 手続きの呼び出し(RPC) | XML のメッセージの規約 |
| エンドポイント | リソースごとに URL | ふつうは1つ(/graphql) | サービスとメソッドの名前 | サービスごと |
| データの形式 | JSON が多い(決まりはない) | JSON | Protocol Buffers が既定 | XML |
| 通信 | HTTP | HTTP(変更は POST) | HTTP/2 | HTTP など |
| エラーの表し方 | ステータスコード | データがあれば2xxで errors を返す | gRPC のステータスコード(0〜16) | Fault 要素(env:Fault) |
GraphQL の公式は、サーバーはふつう /graphql という1つの URL で動き、データを含む応答はエラーがあっても2xxを返す、と説明しています。gRPC の公式は、Protocol Buffers をインターフェースの定義と通信の形式に使えると説明し、通信は HTTP/2 の上で行う仕様です。
判断表:どの方式が合うか
| 状況 | 合う方式 | 理由 |
|---|---|---|
| 外部に公開し、どの言語からも呼ばれる | REST API | curl やブラウザで試せ、HTTP のキャッシュも使える |
| 1画面で多くの種類のデータを組み合わせる | GraphQL | 1回の問い合わせで必要な項目だけ取れる |
| 社内のサービス同士で、型と速さを重視する | gRPC | .proto で型を共有し、HTTP/2 で通信する |
| 既存の XML の連携に合わせる | SOAP | 相手の仕組みに合わせる |
| データの作成・取得・更新・削除が中心 | REST API | URL とメソッドに自然に当てはまる |
| サーバーから変化を知らせたい | REST API + Webhook・WebSocket | REST はクライアントからの依頼が基本 |
同じ画面を REST と GraphQL で作ってリクエスト数を比べた結果は関連記事「GraphQLとRESTの違い|同じ画面を両方で作ってリクエスト数を実測」で、gRPC の4つの通信方式は関連記事「gRPC入門|Pythonで4通信方式を実装、RESTとの使い分けも」で扱っています。いくつかの Web API を組み合わせて1つのサービスを作る考え方は、「マッシュアップとは?Web APIを組み合わせる仕組みと作り方を実演」にまとめています。
REST APIのよくあるつまずき(症状表)と設計のチェック
この節では、REST API を作る・呼ぶときによく出る症状と、原因・確かめ方・直し方が分かります。
| 症状(原文) | 原因 | 確かめ方 | 直し方 |
|---|---|---|---|
415 Unsupported Media Type |
Content-Type が無い・違う | curl -v で送ったヘッダーを見る |
-H 'Content-Type: application/json'、requests は json= |
400・Expecting property name enclosed in double quotes |
JSON の書き方の誤り(キーに引用符が無い) | 送った本文を python3 -m json.tool に通す |
キーと文字列は二重引用符で囲む |
405 Method Not Allowed |
その URL にそのメソッドが無い | 応答の Allow ヘッダー・OPTIONS | 1件の URL(/tasks/1)とコレクションの URL を見直す |
422 と string_too_short(FastAPI) |
項目の値が決まりに合わない | 本文の loc(どの項目か)を見る | 値を直す。API 側は決まりを OpenAPI に書く |
| POST が二重に作られた | 再送・ボタンの二度押し | サーバーのログで同じ本文が2回届いたか | 再試行は冪等なメソッドに限る・冪等キー |
412 Precondition Failed |
取得したあとに別の更新が入った | 今の ETag を GET で取り直す | 取り直してから変更し直す |
| 作成したのに 200 が返る | フレームワークの既定が200 | curl -i の1行目 |
FastAPI なら status_code=201 |
| Session にしたら1件40ms台 | http.server の書き出しと Nagle の待ち | 毎回接続と時間を比べる | disable_nagle_algorithm = True |
作るときに確かめておきたい点です。
- 1URL は名詞、操作はメソッドGET で状態が変わる URL を作らない(GET は安全なメソッド)
- 2作成は201と Locationクライアントは Location で新しいリソースの URL を知る
- 3エラーはステータスコードと problem+json200 の本文に失敗を書かない。どの項目かを本文で返す
- 4405 には Allow、PATCH の415には Accept-Patchクライアントが次に何を送ればよいか分かる
- 5一覧はページングし、次の URL を返すサーバーは読んだ位置を覚えない(ステートレス)
- 6フレームワークの既定の応答を curl -i で確かめるPOST の200・Allow の中身・415と422の違い
よくある質問
Q. REST API とは、簡単にいうと何ですか? A. URL でデータ(リソース)を指し、GET・POST・PUT・PATCH・DELETE のメソッドで取得・作成・更新・削除する Web API です。結果はステータスコードで、データは JSON などで返ります。
Q. REST と REST API の違いは何ですか? A. REST は Roy Fielding が博士論文で示した設計の考え方(6つの制約)で、REST API はその考え方に沿って作った API です。
Q. REST API と RESTful API は違いますか? A. ほぼ同じ意味で使われます。厳密に「6つの制約をすべて満たすか」を区別する人もいますが、ふだんの開発では言い分けないことが多いです。
Q. REST API と Web API の違いは何ですか? A. Web API は HTTP など Web の仕組みで呼ぶ API 全般で、REST API はその一種です。GraphQL や SOAP も Web API に含まれます。
Q. PUT と PATCH はどう使い分けますか? A. PUT はリソースを丸ごと置き換え、PATCH は一部だけ変えます。PUT は冪等で、PATCH は RFC 5789 で冪等とは限らないとされています。手元の JSON Merge Patch のように、同じ PATCH を2回送っても同じ状態になる作り方もあります。
Q. POST と PUT はどちらで作成しますか? A. ID をサーバーが決めるなら POST /tasks(201と Location)、クライアントが URL を決めるなら PUT /tasks/100(無ければ201)です。手元では、同じ POST を2回送ると2件、同じ PUT を2回送ると1件でした。
Q. 冪等とはどういう意味ですか? A. 同じリクエストを何回送っても、サーバーへの意図した効果が1回のときと同じになることです。RFC 9110 では PUT・DELETE と、GET などの安全なメソッドが冪等です。
Q. REST API は必ず JSON で返すのですか? A. 決まりはありません。表現の形式は Content-Type で示し、XML や HTML でも構成できます。今は JSON が広く使われています。
Q. REST API を試すにはどうすればよいですか?
A. curl の -i でステータスコードとヘッダーを見るのが手早い方法です。Python なら requests、ほかに API クライアントのツールも使えます。この記事のサーバーを 127.0.0.1 で動かせば、外部に接続せずに試せます。
Q. HATEOAS(リンク)は入れないといけませんか? A. Fielding の論文では、統一インターフェースの制約の1つです。実際の API では入れていないものも多く、まずは一覧の次のページの URL を Link ヘッダーで返すなど、小さく取り入れる方法があります。
Q. Python で REST API を作るなら何を使いますか? A. 学ぶ目的なら標準ライブラリの http.server で仕組みが見えます。実際のサービスでは、入力の確かめと OpenAPI の定義を作ってくれる FastAPI などのフレームワークが便利です。既定の応答(POST の200など)は確かめてから使います。
まとめ
- REST API は、URL でリソースを指し、HTTP のメソッドで操作し、ステータスコードで結果を返す API。REST は Fielding の論文の6つの制約(コードオンデマンドは任意)。
- GET・HEAD・OPTIONS は安全、PUT・DELETE と安全なメソッドは冪等。手元では同じ POST を2回で2件、同じ PUT を2回で1件になった。
- 作成は201と Location、本文なしは204、入力の誤りは400・422、形式の違いは415、使えないメソッドは405と Allow。エラーの本文は RFC 9457 の problem+json。
- 再試行は冪等なメソッドに限る。urllib3 の Retry も既定で POST を再試行しなかった。
- FastAPI は便利だが、POST の既定は200、Content-Type の違いは422など、既定の応答を curl -i で確かめてから使う。
次に読むとよい記事です。設計の決まりをさらに詳しく決めるときは関連記事「REST APIの設計|URL・ステータスコード・エラー形式の決め方」で扱っています。
参考・出典
確認日はいずれも 2026年11月18日です。
- Roy Thomas Fielding「Architectural Styles and the Design of Network-based Software Architectures」Chapter 5 Representational State Transfer (REST):https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
- IETF「RFC 9110 HTTP Semantics」9.2 Common Method Properties・9.3 Method Definitions・15 Status Codes:https://www.rfc-editor.org/rfc/rfc9110.html
- IETF「RFC 5789 PATCH Method for HTTP」:https://www.rfc-editor.org/rfc/rfc5789.html
- IETF「RFC 9457 Problem Details for HTTP APIs」:https://www.rfc-editor.org/rfc/rfc9457.html
- IETF「RFC 7396 JSON Merge Patch」:https://www.rfc-editor.org/rfc/rfc7396.html
- IETF「RFC 8288 Web Linking」:https://www.rfc-editor.org/rfc/rfc8288.html
- OpenAPI Initiative「OpenAPI Specification」(3.2.1):https://spec.openapis.org/oas/latest.html
- GraphQL「Serving over HTTP」:https://graphql.org/learn/serving-over-http/
- gRPC「Introduction to gRPC」:https://grpc.io/docs/what-is-grpc/introduction/
- gRPC「gRPC over HTTP2」:https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
- AWS「REST とは?」(AWS AppSync デベロッパーガイド):https://docs.aws.amazon.com/ja_jp/appsync/latest/devguide/what-is-rest.html
- Python「http.server」:https://docs.python.org/ja/3/library/http.server.html
- CPython のソースコード「Lib/socketserver.py」(StreamRequestHandler の disable_nagle_algorithm。手元の Python 3.13.18 の同じファイルで確認):https://github.com/python/cpython/blob/3.13/Lib/socketserver.py
- gRPC「Status codes and their use in gRPC」:https://grpc.io/docs/guides/status-codes/
- W3C「SOAP Version 1.2 Part 1: Messaging Framework」5.4 SOAP Fault:https://www.w3.org/TR/soap12-part1/
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「REST APIとは|6つの制約・メソッドの意味とPythonで作る・呼ぶ例」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。