Especificaciones de diseño de URL

Diseño de URL orientado a recursos

Las URL de una API RESTful deben representar "recursos" en lugar de "acciones".

Imagina la URL como una etiqueta de estante en una biblioteca: te indica dónde encontrar cada recurso.

Buen diseño ✅

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

Mal diseño ❌

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

---

Convenciones de nomenclatura de URL

Usa sustantivos en lugar de verbos

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

Usa formas plurales

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

Usa letras minúsculas

• ✅ GET /api/user-orders

• ❌ GET /api/UserOrders

Usa guiones para separar palabras

• ✅ GET /api/user-profiles

• ❌ GET /api/user_profiles

• ❌ GET /api/userProfiles

---

Recursos anidados

Cuando los recursos tienen una relación de dependencia, se pueden usar URL anidadas:

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

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

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

Recomendaciones para niveles de anidación

Parámetros de consulta

Se utilizan para filtrar, ordenar y paginar:

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

---

Control de versiones de API

Para mantener la compatibilidad hacia atrás, la API necesita control de versiones:

Control de versiones por ruta de URL

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

Control de versiones por cabecera de solicitud

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

Otras extensiones