URL-Designspezifikationen
Ressourcenorientiertes URL-Design
RESTful-API-URLs sollten "Ressourcen" statt "Aktionen" darstellen.
Betrachten Sie eine URL als Etikett eines Bibliotheksregals; sie sagt Ihnen, wo Sie welche Ressourcen finden.
Gutes Design ✅
GET /api/users # 获取所有用户 GET /api/users/123 # 获取 ID 为 123 的用户 POST /api/users # 创建新用户 PUT /api/users/123 # 更新用户 123 DELETE /api/users/123 # 删除用户 123
Schlechtes Design ❌
GET /api/getUsers # 动词出现在 URL 中 POST /api/createUser # 动作导向而非资源导向 GET /api/user/delete/123 # 混乱的结构
URL-Benennungskonventionen
Verwenden Sie Substantive statt Verben
- ✅ GET /api/books
- ❌ GET /api/getBooks
Verwenden Sie Pluralformen
- ✅ GET /api/users
- ❌ GET /api/user
Kleinbuchstaben verwenden
-
✅ GET /api/user-orders
- ❌ GET /api/UserOrders
Verwenden Sie Bindestriche, um Wörter zu trennen
✅ GET /api/user-profiles
- ❌ GET /api/user_profiles
- ❌ GET /api/userProfiles
Verschachtelte Ressourcen
Wenn Ressourcen hierarchische Beziehungen haben, können verschachtelte URLs verwendet werden:
// 获取用户 123 的所有订单 GET /api/users/123/orders // 获取用户 123 的订单 456 GET /api/users/123/orders/456 // 为用户 123 创建新订单 POST /api/users/123/orders
Empfehlungen für verschachtelte Hierarchien

Abfrageparameter
Wird zum Filtern, Sortieren und Paginieren verwendet:
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-Versionierung
Um die Abwärtskompatibilität zu erhalten, benötigen APIs eine Versionierung:
URL-Pfad-Versionierung
GET /api/v1/users GET /api/v2/users
Request-Header-Versionierung
GET /api/users Accept: application/vnd.api+json;version=1Andere Erweiterungen