Spécifications de conception d'URL

Conception d'URL orientée ressources

Les URL d'API RESTful doivent représenter des « ressources » plutôt que des « actions ».

Considérez une URL comme une étiquette d'étagère de bibliothèque ; elle vous indique où trouver les ressources.

Bonne conception ✅

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

Mauvaise conception ❌

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

Conventions de nommage des URL

Utilisez des noms plutôt que des verbes

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

Utilisez des formes plurielles

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

Utilisez des lettres minuscules

  • ✅ GET /api/user-orders

  • ❌ GET /api/UserOrders

Utilisez des traits d'union pour séparer les mots

  • ✅ GET /api/user-profiles

  • ❌ GET /api/user_profiles

  • ❌ GET /api/userProfiles

Ressources imbriquées

Lorsque des ressources ont des relations hiérarchiques, des URL imbriquées peuvent être utilisées :

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

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

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

Recommandations pour la hiérarchie imbriquée

Paramètres de requête

Utilisé pour le filtrage, le tri et la pagination :

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=张三

Versionnage d'API

Pour maintenir la compatibilité ascendante, les API doivent être versionnées :

Versionnage par chemin d'URL

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

Versionnage par en-tête de requête

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