Спецификации проектирования URL

Проектирование URL, ориентированное на ресурсы

URL-адреса RESTful API должны представлять «ресурсы», а не «действия».

Представьте 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
Другие расширения