Buenas prácticas de diseño de APIs REST

1 Introducción

Una API REST puede estar técnicamente correcta y aun así ser difícil de usar si no sigue buenas prácticas de diseño.

  • Una API mal diseñada genera frustración en los clientes y aumenta el costo de mantenimiento.
  • Una API bien diseñada es intuitiva, predecible y consistente, lo que la convierte en un producto profesional.

👉 En este capítulo veremos las mejores prácticas para diseñar APIs REST limpias y efectivas.

2 Consistencia en endpoints y rutas

Usar sustantivos, no verbos

/crearUsuario   # incorrecto
/usuarios      # correcto

👉 El método HTTP ya define la acción (POST /usuarios crea un usuario).

Usar plural para colecciones

/usuario   # incorrecto
/usuarios  # correcto

Usar minúsculas y guiones medios

/HistorialCompras   # incorrecto
/historial-compras # correcto

Mantener jerarquía clara

/usuarios/1/pedidos       # pedidos del usuario 1
/productos/15/comentarios # comentarios del producto 15

3 Uso correcto de métodos HTTP

Cada método debe usarse de acuerdo con su semántica:

  • GET: obtener información (nunca modificar).
  • POST: crear un recurso nuevo.
  • PUT: actualizar un recurso completo.
  • PATCH: actualizar parcialmente un recurso.
  • DELETE: eliminar un recurso.

👉 Esto evita confusión y mantiene la API predecible.

4 Uso adecuado de códigos de estado

Siempre devolver códigos HTTP correctos:

  • 200 OK: operación exitosa.
  • 201 Created: recurso creado.
  • 204 No Content: eliminación sin datos.
  • 400 Bad Request: error en la petición del cliente.
  • 401 Unauthorized: falta autenticación.
  • 403 Forbidden: no tiene permisos.
  • 404 Not Found: recurso no existe.
  • 500 Internal Server Error: error inesperado del servidor.

👉 Nunca devolver siempre 200, incluso en errores.

5 Estructura clara en respuestas JSON

  • Siempre usar JSON válido y consistente.
  • Mantener nombres de campos en minúsculas y snake_case o camelCase (elegir uno y no mezclar).
  • Responder con objetos bien estructurados.

Ejemplo correcto

{
  "id": 1,
  "nombre": "Ana",
  "email": "ana@ejemplo.com"
}

Ejemplo incorrecto

["Ana", "ana@ejemplo.com"]  # difícil de entender

👉 Además, incluir mensajes claros en errores:

{
  "error": "Bad Request",
  "mensaje": "El campo 'email' es obligatorio"
}

6 Paginación y filtros

Cuando una colección puede devolver miles de resultados, paginación y filtros son indispensables.

Ejemplo

GET /usuarios?pagina=2&limite=20

Respuesta

{
  "pagina": 2,
  "limite": 20,
  "total": 95,
  "usuarios": [
    { "id": 21, "nombre": "Luis" },
    { "id": 22, "nombre": "Laura" }
  ]
}

👉 Esto mejora el rendimiento y evita respuestas demasiado grandes.

7 Autenticación y seguridad

  • Usar HTTPS siempre.
  • No pasar credenciales en la URL.
  • Usar tokens (API Keys, JWT).
  • Controlar permisos por roles.
  • Evitar exponer información sensible en errores (500 debe ser genérico).

👉 Una API sin seguridad es una puerta abierta a ataques.

8 Versionado claro

Siempre versionar la API desde el inicio:

/api/v1/usuarios
/api/v2/usuarios

👉 Permite evolucionar sin romper compatibilidad con clientes antiguos.

9 Documentación automática

  • Incluir documentación con OpenAPI/Swagger.
  • Documentar ejemplos de requests y responses.
  • Incluir lista de errores posibles para cada endpoint.

👉 La documentación es parte del producto, no un accesorio.

10 Estándar en mensajes de error

Definir un formato único para errores. Ejemplo:

{
  "error": "Not Found",
  "mensaje": "El producto con id 99 no existe",
  "codigo": 404,
  "timestamp": "2025-09-10T12:30:00Z",
  "ruta": "/productos/99"
}

👉 Esto ayuda a los clientes a interpretar los fallos de manera consistente.

11 Estandarizar convenciones de nombres

  • Campos booleanos: prefijo is_ o activo. Ejemplo: "activo": true.
  • Fechas y horas: siempre en formato ISO 8601 (2025-09-10T12:30:00Z).
  • Monedas y precios: incluir decimales y, si es necesario, el código de moneda. Ejemplo: "precio": 1500.00, "moneda": "USD".

12 Ejemplo de una API bien diseñada

Endpoint

GET /api/v1/productos?categoria=electronica&pagina=1&limite=2

Respuesta

{
  "pagina": 1,
  "limite": 2,
  "total": 25,
  "productos": [
    { "id": 101, "nombre": "Notebook Gamer", "precio": 2200.00, "stock": true },
    { "id": 102, "nombre": "Auriculares Bluetooth", "precio": 150.00, "stock": false }
  ]
}

👉 Claridad en la ruta, paginación, nombres consistentes y uso correcto de JSON.

13 Conclusión del capítulo

Las buenas prácticas en diseño de APIs REST hacen la diferencia entre una API usable y una API profesional, confiable y escalable.

  • Endpoints claros y consistentes.
  • Uso correcto de métodos HTTP y códigos de estado.
  • Respuestas JSON bien estructuradas.
  • Manejo estándar de errores.
  • Seguridad (HTTPS, tokens).
  • Versionado y documentación clara.

👉 En resumen: una API bien diseñada habla el mismo idioma que los desarrolladores.

Retornar