Diseño de URL API RESTful: Guía de Endpoints Amigables para Desarrolladores

Mejores prácticas para diseño de endpoints API RESTful. Crea estructuras de URL API limpias, consistentes y escalables.

En el diseño de API RESTful, la estructura de URL afecta directamente la usabilidad y mantenibilidad de tu API. En esta guía, aprendemos a diseñar endpoints de API amigables para desarrolladores.

Fundamentos REST

¿Qué es REST?

Representational State Transfer (REST) es un estilo arquitectónico para APIs web. Representa recursos a través de URLs y usa métodos HTTP.

Métodos HTTP

GET    → Leer recurso
POST   → Crear nuevo recurso
PUT    → Reemplazar recurso completamente
PATCH  → Actualizar recurso parcialmente
DELETE → Eliminar recurso

Principios de Diseño de URL

1. Usar Sustantivos, No Verbos

# INCORRECTO - Usando verbos
GET  /getUsers
POST /createUser

# CORRECTO - Usando sustantivos
GET    /users
POST   /users

2. Usar Sustantivos en Plural

# INCORRECTO
/user
/product

# CORRECTO
/users
/products

3. Estructura Jerárquica

# Órdenes del usuario
GET /users/123/orders

# Items de la orden
GET /orders/456/items

Versionado

Versión en URL

# Método más común
https://api.example.com/v1/users
https://api.example.com/v2/users

Filtrado, Ordenación y Paginación

Filtrado

# Filtrado simple
GET /products?category=electronics

# Operadores de comparación
GET /products?price[gte]=100&price[lte]=500

Ordenación

# Ordenación por un campo
GET /products?sort=price
GET /products?sort=-price        # Descendente

Paginación

# Basada en offset
GET /products?page=2&per_page=20

# Basada en cursor (más performante)
GET /products?cursor=abc123&limit=20

Códigos de Estado HTTP

# Éxito
200 OK           → GET, PUT, PATCH exitoso
201 Created      → POST exitoso
204 No Content   → DELETE exitoso

# Errores de Cliente
400 Bad Request  → Solicitud inválida
401 Unauthorized → Autenticación requerida
403 Forbidden    → Sin permiso
404 Not Found    → Recurso no encontrado

Conclusión

URLs de API bien diseñadas aumentan la usabilidad de tu API y facilitan el mantenimiento. Crea APIs amigables para desarrolladores usando nomenclatura consistente, jerarquía lógica y métodos HTTP estándar.