Web・ネットワーク
PR

REST APIとは?HTTPメソッド・ステータスコードの意味とcurlでの試し方

REST APIとは?HTTPメソッド・ステータスコードの意味とcurlでの試し方
hr
記事内に商品プロモーションを含む場合があります

Web サービスやアプリの開発では、REST API(レスト エーピーアイ)という言葉を毎日のように耳にします。けれども、「REST って何の略?」「PUT と PATCH の違いは?」と聞かれると、意外と説明に困るものです。

この記事では、API と REST の考え方(リソースと URL、HTTP メソッド、ステータスコード、JSON)を、HTTP の仕様書 RFC 9110 の定義を確かめながら解説します。後半では、Python の標準ライブラリだけで作った小さな REST API(ToDo リスト)を自分の PC で動かし、curl.exe と Python から GET・POST・PUT・DELETE を送った実際の結果を載せます。

実行結果は Windows 11・PowerShell 5.1・Python 3.12・Windows 標準の curl.exe 8.21.0 で確かめました(2026 年 10 月)。練習の相手は自分の PC(127.0.0.1)だけにし、他人のサービスに練習のリクエストを送らないようにしましょう。

API とは

API(Application Programming Interface)は、プログラムどうしがやり取りするための窓口と、その決まりごとです。人が画面のボタンを押して使うのではなく、プログラムが「この形でお願いすれば、この形で答えが返る」という約束に従って機能を呼び出します。

API という言葉は広く、ライブラリの関数の使い方なども API と呼びます。この記事で扱うのは、そのうち HTTP(Web のやり取りの決まり)を使ってネットワーク越しに呼び出す API、いわゆる Web API です。返ってくるのは人が読む HTML ではなく、プログラムが読みやすい JSON などのデータであることが多くなります。

REST とは:Roy Fielding の論文から生まれた言葉

REST は Representational State Transfer の略です。HTTP の仕様の作成にかかわった Roy Thomas Fielding が、2000 年にカリフォルニア大学アーバイン校に提出した博士論文「Architectural Styles and the Design of Network-based Software Architectures」の第 5 章で名付けた、ネットワーク上のソフトウェアの設計の考え方(アーキテクチャスタイル)です。ソフトウェアや規格の名前ではありません。

論文の 5.1 節では、REST を次の制約(守るべき条件)の組み合わせとして説明しています。

制約(論文の名前)かみくだいた意味
Client-Server画面の側とデータを持つ側を分ける
Statelessサーバーは前のリクエストを覚えない。毎回必要な情報をすべて送る
Cacheレスポンスを使い回してよいかを示す
Uniform Interfaceどのリソースも同じ決まった方法で操作する
Layered System間にプロキシなどの層をはさめる
Code-On-Demand(任意)サーバーから JavaScript などを送って動かせる

このうち「Uniform Interface(統一されたインターフェース)」が REST API の形をよく表しています。論文はその中身として、リソースの識別、表現(JSON などのデータ)を通した操作、それだけで意味が分かるメッセージ、ハイパーメディア(リンク)による状態の移り変わり、の 4 つを挙げています。

実際の開発現場で「REST API」と呼ばれているものは、論文の制約をすべて満たしているとは限りません。多くの場合は、「URL でデータ(リソース)を表し、HTTP のメソッドで操作を表し、結果をステータスコードと JSON で返す API」という意味で使われています。

考え方 1:リソースを URL で表す

Fielding の論文は、REST の中心となる考え方を「リソース」とし、名前を付けられる情報はすべてリソースになりうると説明しています。ToDo アプリなら「ToDo の一覧」や「2 番の ToDo」がリソースです。REST API では、リソースごとに URL を決めます。

URL(パス)表すリソース
/todosToDo の一覧(コレクション)
/todos/2id が 2 の ToDo 1 件

ポイントは、URL には「もの(名詞)」を書き、「何をするか(動詞)」は書かないことです。/getTodos や /deleteTodo?id=2 のように URL に動作を入れるのではなく、同じ /todos/2 に対して、次に説明する HTTP メソッドを変えて「取得」「更新」「削除」を表します。

考え方 2:操作を HTTP メソッドで表す

HTTP のリクエストには、必ず「メソッド」が付いています。ブラウザーでページを開くときは GET、フォームを送信するときはたいてい POST です。REST API では、よく次の 5 つを使います。

メソッドREST API でのよくある使い方例安全冪等
GET取得するGET /todos/2○○
POST新しく作る(id はサーバーが決める)POST /todos××
PUT丸ごと置き換える(なければ作る)PUT /todos/2×○
PATCH一部だけ変更するPATCH /todos/2××(作り方による)
DELETE削除するDELETE /todos/2×○

GET・POST・PUT・DELETE は HTTP の意味(セマンティクス)を定める RFC 9110(2022 年 6 月)で、PATCH は別の RFC 5789(2010 年 3 月)で定義されています。

HTTP メソッドと URL(リソース)の対応。/todos(ToDo の一覧)には GET で一覧を取得し、POST で新しく作る。/todos/2(id が 2 の ToDo 1 件)には GET で取得、PUT で丸ごと置き換え、PATCH で一部だけ変更、DELETE で削除する。
図 1:同じ URL に、メソッドを変えて操作を表す

「安全」と「冪等」の意味(RFC 9110 の定義)

表の「安全」「冪等(べきとう)」は、RFC 9110 の 9.2 節で定義されている性質です。

  • 安全(safe):本質的に読み取り専用で、クライアントがサーバーの状態の変更を求めないメソッド。RFC 9110 のメソッドでは GET・HEAD・OPTIONS・TRACE。
  • 冪等(idempotent):同じリクエストを何回送っても、サーバーへの意図した効果が 1 回のときと同じになるメソッド。RFC 9110 のメソッドでは PUT・DELETE と安全なメソッド。

たとえば「2 番を『done: true』の内容に置き換える」PUT は、3 回送っても結果は同じです。「2 番を削除する」DELETE も、1 回目で消えたあとは何度送っても「消えている」状態は変わりません(2 回目以降のレスポンスは 404 になることがありますが、効果は同じです)。一方、POST で「1 件追加」を 3 回送ると、ToDo が 3 件増えてしまいます。

RFC 9110 は、冪等なメソッドは通信が途中で切れたときに自動で再送できると説明し、冪等でないメソッドは、本当に冪等だと分かる手段がない限り自動で再送すべきでない(SHOULD NOT)としています。PATCH について RFC 5789 は「安全でも冪等でもない」としつつ、冪等になるように作ることもできると書いています。

PUT と PATCH の違い

RFC 9110 は PUT を「対象のリソースの状態を、送った内容で作成または置き換える」メソッドとしています。つまり PUT ではリソースの全体を送ります。一方 RFC 5789 の PATCH は、「どう変更するか」を送って一部だけを変えるメソッドです。後で作るサーバーでは、次のように動きます。

  • PATCH /todos/2 に {"done": false} を送る → done だけが変わり、title はそのまま
  • PUT /todos/2 に {"done": true} だけを送る → title がないので 400(Bad Request)。PUT は全体の置き換えなので、title と done の両方を求める作りにしている。実際の API では、送らなかった項目が空になるものもあるので、仕様書で確認する
PUT と PATCH の違い。いまの /todos/2 は id 2、title report、done true。PATCH /todos/2 に done false だけを送ると 200 OK で id 2、title report、done false になり、done だけが変わって title はそのまま。PUT /todos/2 に done true だけを送ると、title がないので 400 Bad Request になる。PUT は全体の置き換えなので title と done の両方が必要。
図 2:PUT と PATCH の違い(この記事の練習用サーバーの場合)

考え方 3:結果をステータスコードで返す

レスポンスの 1 行目には、3 桁のステータスコードが入ります。RFC 9110 では、1 桁目で次の 5 つの分類が決まっています。1xx は情報、2xx は成功、3xx はリダイレクト、4xx はクライアントのエラー(リクエストの側に問題がある)、5xx はサーバーのエラーです。REST API でよく使うのは次のコードです。

コード意味REST API での主な使いどころ
200 OK成功GET で取得できた、PUT・PATCH で更新できた
201 Created新しいリソースを作ったPOST で作成した。作ったリソースの場所を Location ヘッダーで示す
204 No Content成功したが、返す本文はないDELETE で削除した
400 Bad Requestリクエストの形が正しくないJSON が壊れている、必須の項目がない
404 Not Found見つからない存在しない id を指定した
405 Method Not Allowedそのリソースでは使えないメソッド一覧(/todos)に DELETE を送った
500 Internal Server Errorサーバー内部のエラーサーバーのプログラムの不具合など

RFC 9110 では、201 で作ったリソースは Location ヘッダー(なければリクエストした URL)で示すこと、405 を返すときは使えるメソッドの一覧を Allow ヘッダーに入れなければならない(MUST)ことが決められています。ほかのコードは「HTTPステータスコード検索」で調べられます。

考え方 4:データは JSON でやり取りする

REST そのものはデータの形式を決めていませんが、今の Web API では JSON(ジェイソン)がよく使われます。送る側は、本文が JSON であることを Content-Type: application/json というヘッダーで伝えます。ToDo 1 件は、たとえば次のような JSON で表します。

{"id": 2, "title": "report", "done": false}

送る JSON や返ってきた JSON が読みにくいときは、「JSON整形ツール」に貼ると整形と構文チェックができます。

Python だけで小さな REST API を作って試す

ここからは、実際に REST API を動かしてみます。Python の標準ライブラリ(http.server と json)だけで作った、メモリー上の ToDo リストです。追加のインストールは不要です。

サーバーのコード(todo_api.py)

次のコードを、作業用のフォルダーに todo_api.py という名前(文字コードは UTF-8)で保存します。

# todo_api.py : 練習用の小さな REST API(データはメモリー上だけ。127.0.0.1 で待ち受ける)
import json
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

HOST, PORT = "127.0.0.1", 8000
todos = {1: {"id": 1, "title": "buy milk", "done": False}}
next_id = 2
lock = threading.Lock()  # 同時に POST されても id が重ならないように


class TodoHandler(BaseHTTPRequestHandler):
    def send_json(self, status, data=None, headers=None):
        body = b"" if data is None else json.dumps(data, ensure_ascii=False).encode("utf-8")
        self.send_response(status)
        for name, value in (headers or {}).items():
            self.send_header(name, value)
        if data is not None:
            self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def read_json(self):
        length = int(self.headers.get("Content-Length") or 0)
        if length > 10_000:  # 大きすぎる本文は受け取らない
            return None
        try:
            data = json.loads(self.rfile.read(length).decode("utf-8"))
        except (UnicodeDecodeError, json.JSONDecodeError):
            return None
        return data if isinstance(data, dict) else None

    def target(self, *allowed):
        # "/todos" は一覧(list)、"/todos/3" は 3 番の ToDo(item)
        parts = self.path.split("?")[0].strip("/").split("/")
        todo_id = int(parts[1]) if len(parts) == 2 and parts[1].isdigit() else None
        if parts == ["todos"]:
            kind = "list"
        elif parts[0] == "todos" and todo_id in todos:
            kind = "item"
        else:
            self.send_json(404, {"error": "見つかりません"})
            return None, None
        if kind not in allowed:
            allow = "GET, POST" if kind == "list" else "GET, PUT, PATCH, DELETE"
            self.send_json(405, {"error": "このメソッドは使えません"}, {"Allow": allow})
            return None, None
        return kind, todo_id

    def do_GET(self):
        kind, todo_id = self.target("list", "item")
        if kind == "list":
            self.send_json(200, list(todos.values()))
        elif kind == "item":
            self.send_json(200, todos[todo_id])

    def do_POST(self):
        global next_id
        if self.target("list")[0] is None:
            return
        data = self.read_json()
        if data is None or not isinstance(data.get("title"), str) or not data["title"]:
            return self.send_json(400, {"error": "title(文字列)が必要です"})
        with lock:
            todo = {"id": next_id, "title": data["title"], "done": bool(data.get("done", False))}
            todos[next_id] = todo
            next_id += 1
        self.send_json(201, todo, {"Location": f"/todos/{todo['id']}"})

    def do_PUT(self):  # 丸ごと置き換える:title と done の両方が必要
        kind, todo_id = self.target("item")
        if kind is None:
            return
        data = self.read_json()
        if data is None or not isinstance(data.get("title"), str) or not isinstance(data.get("done"), bool):
            return self.send_json(400, {"error": "title と done の両方が必要です"})
        todos[todo_id] = {"id": todo_id, "title": data["title"], "done": data["done"]}
        self.send_json(200, todos[todo_id])

    def do_PATCH(self):  # 一部だけ変える:送られた項目だけを更新する
        kind, todo_id = self.target("item")
        if kind is None:
            return
        data = self.read_json()
        if data is None:
            return self.send_json(400, {"error": "JSON の形が正しくありません"})
        for key, typ in (("title", str), ("done", bool)):
            if isinstance(data.get(key), typ):
                todos[todo_id][key] = data[key]
        self.send_json(200, todos[todo_id])

    def do_DELETE(self):
        kind, todo_id = self.target("item")
        if kind is None:
            return
        del todos[todo_id]
        self.send_json(204)


class TodoServer(ThreadingHTTPServer):
    allow_reuse_address = False  # Windows で同じポートに二重に起動できてしまうのを防ぐ


if __name__ == "__main__":
    server = TodoServer((HOST, PORT), TodoHandler)
    print(f"http://{HOST}:{PORT}/todos で待ち受け中(Ctrl+C で終了)")
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass

Python の http.server は、リクエストのメソッド名から do_GET・do_POST のような名前のメソッドを呼び出します。target で URL が一覧(/todos)か 1 件(/todos/数字)かを見分け、ない id には 404、使えないメソッドには 405 を返します。最後の allow_reuse_address = False は、Windows で同じポートのサーバーを誤って 2 つ起動できてしまうのを防ぐ設定です(この行がないと、2 つ目もエラーにならずに起動しました)。

注意:このサーバーは練習用です。待ち受けるアドレスを 127.0.0.1(自分の PC からしか接続できないアドレス)にしているので、ほかの PC からは使えません。HOST を 0.0.0.0 に変えたり、インターネットに公開したりしないでください。Python の公式ドキュメントも、http.server は基本的なセキュリティチェックしか実装しておらず、本番環境での利用は推奨しないと警告しています。認証もないので、公開すると誰でもデータを書き換えられます。

サーバーを起動する

PowerShell で todo_api.py を保存したフォルダーに移動し、次のコマンドを実行します(py がない環境では python や python3)。

py todo_api.py
http://127.0.0.1:8000/todos で待ち受け中(Ctrl+C で終了)

この画面は開いたままにし、以降のコマンドは別の PowerShell の画面で実行します。8000 番がほかのプログラムに使われていると OSError: [WinError 10048] というエラーで起動しないので、PORT を 8001 などに変え、以降の URL もそろえます。終わるときは、サーバーの画面で Ctrl+C を押します。データはメモリー上にしかないので、止めると消えます。

curl.exe で GET・POST・PUT・DELETE を送る

PowerShell 5.1 では curl が別のコマンド(Invoke-WebRequest)の別名になっているので、curl.exe と書きます。-i はレスポンスのヘッダーも表示するオプション、--json は JSON を送るオプション(curl 7.82.0 以降)です。curl の詳しい使い方は「curlコマンドの使い方」で解説しています。

まず、一覧を GET します。

curl.exe http://127.0.0.1:8000/todos
[{"id": 1, "title": "buy milk", "done": false}]

次に、POST で 1 件追加します。PowerShell 5.1 では、JSON の「”」の前に「\」を付けます。

curl.exe -i --json '{\"title\":\"report\"}' http://127.0.0.1:8000/todos
HTTP/1.0 201 Created
Server: BaseHTTP/0.6 Python/3.12.6
Date: Sun, 18 Oct 2026 00:04:18 GMT
Location: /todos/2
Content-Type: application/json; charset=utf-8
Content-Length: 43

{"id": 2, "title": "report", "done": false}

ステータスは 201 Created で、Location ヘッダーに新しい ToDo の場所 /todos/2 が入っています。id はクライアントが決めたのではなく、サーバーが決めて返しています。

PUT で、2 番を「完了(done: true)」の内容に置き換えます。--json を付けると curl は POST を使うので、-X PUT でメソッドを指定します。

curl.exe -i -X PUT --json '{\"title\":\"report\",\"done\":true}' http://127.0.0.1:8000/todos/2
HTTP/1.0 200 OK
Server: BaseHTTP/0.6 Python/3.12.6
Date: Sun, 18 Oct 2026 00:04:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 42

{"id": 2, "title": "report", "done": true}

同じ PUT をもう一度送っても、結果は同じ {"id": 2, "title": "report", "done": true} でした。これが「冪等」です。PATCH なら、変えたい項目だけを送れます。次のコマンドでは、title はそのままで done だけが false に戻った {"id": 2, "title": "report", "done": false} が返りました。

curl.exe -X PATCH --json '{\"done\":false}' http://127.0.0.1:8000/todos/2

最後に DELETE で削除します。

curl.exe -i -X DELETE http://127.0.0.1:8000/todos/2
HTTP/1.0 204 No Content
Server: BaseHTTP/0.6 Python/3.12.6
Date: Sun, 18 Oct 2026 00:04:18 GMT
Content-Length: 0

204 No Content なので本文はありません。もう一度 curl.exe -i http://127.0.0.1:8000/todos/2 で取得すると、HTTP/1.0 404 Not Found と {"error": "見つかりません"} が返り、削除されたことが確かめられます。また、一覧に DELETE を送る(curl.exe -i -X DELETE http://127.0.0.1:8000/todos)と、HTTP/1.0 405 Method Not Allowed と、使えるメソッドを示す Allow: GET, POST ヘッダーが返りました。

Python(urllib)から呼び出す

プログラムから API を呼ぶ例です。標準ライブラリの urllib.request だけを使います。次のコードを todo_client.py として保存し、サーバーを起動したまま実行します。

import json
import urllib.error
import urllib.request

BASE = "http://127.0.0.1:8000"


def call(method, path, data=None):
    body = None if data is None else json.dumps(data).encode("utf-8")
    req = urllib.request.Request(BASE + path, data=body, method=method)
    if body is not None:
        req.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(req, timeout=5) as res:
            text = res.read().decode("utf-8")
            return res.status, (json.loads(text) if text else None)
    except urllib.error.HTTPError as e:  # 4xx・5xx はここに来る
        return e.code, json.loads(e.read().decode("utf-8"))


print(call("GET", "/todos"))
status, todo = call("POST", "/todos", {"title": "牛乳を買う"})
print(status, todo)
print(call("PUT", f"/todos/{todo['id']}", {"title": "牛乳を2本買う", "done": True}))
print(call("DELETE", f"/todos/{todo['id']}"))
print(call("GET", f"/todos/{todo['id']}"))
py todo_client.py

サーバーを起動し直した直後に実行した結果です。

(200, [{'id': 1, 'title': 'buy milk', 'done': False}])
201 {'id': 2, 'title': '牛乳を買う', 'done': False}
(200, {'id': 2, 'title': '牛乳を2本買う', 'done': True})
(204, None)
(404, {'error': '見つかりません'})

urllib.request.urlopen は、ステータスコードが 4xx・5xx のときに例外 urllib.error.HTTPError を出します。そのため、最後の 404 は except の中で受け取っています。JSON の読み書き(json.dumps・json.loads)については「PythonでJSONを扱う方法」で詳しく解説しています。

よくある間違い・トラブル

GET で削除や更新をしてしまう

/todos/delete?id=2 のような URL を作り、GET で削除できるようにするのは避けましょう。GET は「安全」なメソッドなので、検索エンジンのクローラーやリンクの先読みなどの自動処理が、気軽にアクセスしてきます。RFC 9110 も「page?do=delete」のような例を挙げ、危険な操作は安全なメソッドでアクセスされたときには無効にしなければならない(MUST)としています。データを変える操作は POST・PUT・PATCH・DELETE で行います。

POST を自動で再送して二重に登録される

通信エラーのときに「失敗したらもう一度」と POST を自動で再送する処理を書くと、実は 1 回目が成功していて、データが 2 件登録されることがあります。POST は冪等ではないからです。再送してよいのは、GET・PUT・DELETE のような冪等な操作か、API 側で二重登録を防ぐ仕組みがある場合に限りましょう。

PowerShell で JSON が壊れる・送れない

PowerShell 5.1 で「\」を付けずに curl.exe -i --json '{"title":"x"}' http://127.0.0.1:8000/todos と送ると、途中で「”」が消えて JSON でなくなり、サーバーは 400 Bad Request を返しました。また、「\」を付けても、'{\"title\":\"write report\"}' のように値にスペースが入ると、次のエラーになって送られませんでした。

curl: (3) unmatched close brace/bracket in position 8:
report"}
       ^

スペースや日本語を含む JSON は、ファイルに保存して送ると確実です。メモ帳などで {"title": "牛乳を買う", "done": false} と書いた todo.json を UTF-8(BOM なし)で保存し、次のように「@ファイル名」で指定します(PowerShell では @ の付いた引数を「”」で囲みます)。この方法で送ると、201 Created で日本語のタイトルの ToDo が作られました(先頭に BOM が付いたファイルでは、このサーバーは JSON として読めず 400 になりました)。なお、Git Bash では '{"title":"write report"}' のように「\」なしで書けば、スペース入りでも正しく登録できました。

curl.exe -i --json "@todo.json" http://127.0.0.1:8000/todos

よくある質問

PUT で新しく作ることはできますか?

RFC 9110 では、PUT は「作成または置き換え」のメソッドで、まだないリソースを PUT で作ったときは 201 Created を返さなければならない(MUST)とされています。ただし、それができるのはクライアントが URL(id)を決められる API の場合です。今回のサーバーのように id をサーバーが決める API では、作成は POST で行い、存在しない id への PUT は 404 にしています。

実際の API では認証はどうするのですか?

多くの API では、API キーやアクセストークンを Authorization などのヘッダーに付けて送り、通信は HTTPS で暗号化します。キーやトークンはパスワードと同じように扱い、ソースコードに書いて Git に入れないようにしましょう。HTTPS の仕組みは「HTTPとHTTPSの違いとは?」で解説しています。

まとめ

REST API は、URL でリソースを表し、HTTP メソッドで操作を表し、結果をステータスコードと JSON で返す API です。GET は安全、PUT と DELETE は冪等、POST は冪等でない、という性質を押さえておくと、再送やエラー処理で迷わなくなります。

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました