URL設計規範

リソース指向の URL 設計

RESTful API の URL は「リソース」を表すべきであり、「アクション」ではありません。

URL を図書館の書架ラベルだと考えてください。どこでどのリソースを見つけられるかを示しています。

良い設計 ✅

GET /api/users          # 获取所有用户
GET /api/users/123      # 获取 ID 为 123 的用户
POST /api/users         # 创建新用户
PUT /api/users/123      # 更新用户 123
DELETE /api/users/123   # 删除用户 123

悪い設計 ❌

GET /api/getUsers       # 动词出现在 URL 中
POST /api/createUser    # 动作导向而非资源导向
GET /api/user/delete/123 # 混乱的结构

---

URL命名規範

動詞ではなく名詞を使用する

• ✅ GET /api/books
• ❌ GET /api/getBooks

複数形を使用する

• ✅ GET /api/users
• ❌ GET /api/user

小文字を使用する

• ✅ GET /api/user-orders

• ❌ GET /api/UserOrders

ハイフンで単語を区切る

• ✅ GET /api/user-profiles

• ❌ GET /api/user_profiles

• ❌ GET /api/userProfiles

---

ネストされたリソース

リソース間に従属関係がある場合、ネストされた URL を使用できます：

// 获取用户 123 的所有订单
GET /api/users/123/orders

// 获取用户 123 的订单 456
GET /api/users/123/orders/456

// 为用户 123 创建新订单
POST /api/users/123/orders

ネスト階層の推奨事項

クエリパラメータ

フィルタリング、並べ替え、ページネーションに使用されます：

javascript// 分页
GET /api/users?page=1&limit=10

// 过滤
GET /api/users?status=active&city=beijing

// 排序
GET /api/users?sort=created_at&order=desc

// 搜索
GET /api/users?search=张三

---

API バージョン管理

後方互換性を維持するために、API にはバージョン管理が必要です：

URL パスによるバージョン管理

GET /api/v1/users
GET /api/v2/users

リクエストヘッダーによるバージョン管理

GET /api/users
Accept: application/vnd.api+json;version=1

その他の拡張機能