抜粋：APIと「エンドポイント」の違い、Web以外での使われ方、Pythonでの扱い方、良いAPI設計・悪いAPI設計の具体例、URL設計の基準、そしてRESTとRPCの違いをシンプルにまとめました。
はじめに — API と「エンドポイント」って何？
API は「アプリ同士が約束ごと（ルール）で会話する仕組み」です。 エンドポイント は、その会話の「届け先の住所（URLや名前）」だと考えてください。 住所を指定して「このデータちょうだい」「これを作って」などのお願い（リクエスト）を送るイメージです。
重要ポイント：APIエンドポイントはWebだけの言葉ではない
- Web API：URL（例:
https://example.com/users）を使うことが多い。 - IoT・スマート家電：ネットワーク上のアドレスやコマンドでエンドポイントが存在する。
- ゲームや内部システム：URL形式のものもあれば「関数名」や「操作名」でエンドポイントを表すこともある。
- まとめ：エンドポイント＝「お願いを届ける場所」。形はURLだったり関数名だったりする。
Pythonでの扱い — 「エンドポイント ≒ パス」で良い？
Web API にアクセスする Python プログラムでは、URL のパス部分（例: /users）がそのままエンドポイントです。例えば requests を使うと：
import requests
resp = requests.get("https://example.com/api/users")
print(resp.json()) # ユーザー一覧が返る想定ただし、Python内部の関数呼び出し（def get_user()など）は「内部処理」であって通常「エンドポイント」とは呼びません。
良い API の例（使いやすさ重視）
CRUD（作る・読む・更新・消す）をわかりやすく表現した REST スタイルの例：
GET /users → ユーザー一覧を取得
POST /users → ユーザーを作成
GET /users/123 → 123番のユーザーを取得
PUT /users/123 → 123番のユーザーを更新
DELETE /users/123 → 123番のユーザーを削除ポイント：URLは名詞中心、HTTPメソッド（GET/POST/PUT/DELETE）で操作を表す。
悪い API の失敗例（よくあるアンチパターン）
GET /getUserList
POST /saveUserData
GET /userInfo?id=123
POST /changeUser
POST /removeUser?id=123問題点のまとめ：
- URLに動詞（create/deleteなど）が入り、規則性がない。
- HTTPメソッドと意味が合っていない（削除なのにPOSTを使う等）。
- 追加や拡張時に混乱しやすく保守性が低い。
URL（エンドポイント）の決め方：実践的ルール
- 名詞で考える：リソース（対象物）をURLにする（例:
/users、/books）。 - 階層は関係性で表現：
/users/123/postsは「ユーザー123の投稿一覧」。 - 複雑操作はサブパスで例外対応：例：
POST /users/123/reset-passwordは実務でよく使う。 - バージョンは先頭に：将来互換性を保つために
/v1/usersのようにする。 - HTTPステータスと返すJSONを設計：成功・失敗（200/201/400/404/500など）と、返すデータ形式を明確に。
REST と RPC の違い（超シンプル）
| 特徴 | REST | RPC |
|---|---|---|
| URLの形 | 名詞中心（/users） | 動詞中心（/getUser） |
| 操作の表現 | HTTPメソッド（GET/POST/PUT/DELETE） | 関数を呼ぶイメージ（POSTで操作指定） |
| 向いている用途 | 外部公開API、CRUD中心 | 内部API、複雑処理や遅延が許されない処理 |
どちらが良いかはケースバイケース。外向けなら REST、内部や処理指向なら RPC が選ばれることが多いです。
実例：簡単なコード例（1） — Python から GET で呼ぶ
import requests
url = "https://api.example.com/v1/users/123"
resp = requests.get(url)
if resp.status_code == 200:
user = resp.json()
print("ユーザー名:", user["name"])
else:
print("エラー:", resp.status_code)実例：簡単なコード例（2） — FastAPI でエンドポイントを作る
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class User(BaseModel):
name: str
# ユーザー作成
@app.post("/users")
def create_user(user: User):
return {"id": 1, "name": user.name}
# ユーザー取得
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"id": user_id, "name": "Amiya"}ポイント：URL（/users）・メソッド（GET/POST）・返すデータの形（JSON）を明示しているのが良い設計です。
よくある質問（FAQ）
Q. URLに素敵な名前を付けたいけど動詞入れてもダメ？
A. 単発の操作（例：パスワードをリセットする）などは /users/{id}/reset-password のようにサブパスで例外的に動詞を使うのはOKです。ただし規則性を壊さないように注意。
Q. RESTとGraphQLはどっちがいい？
A. データを自由に取得したいなら GraphQL、CRUD中心でシンプルにしたいなら REST が向いています。
まとめ（友達に教えるときの一言）
「APIエンドポイント」は “お願いを届ける住所” です。
良いAPIは住所（URL）がわかりやすく、お願いの仕方（メソッド）が決まっていて、返ってくるもの（JSONやステータス）も予測しやすい設計になっています。
コメント