APIs REST que no dan guerra al equipo

Las buenas APIs aburren en el buen sentido: son predecibles, coherentes y fáciles de razonar. Cuando la superficie es simple, el equipo entrega más rápido y los clientes rompen menos.

Esta es una lista corta que sirve tanto para diseñar endpoints nuevos como para revisar los que ya tienes.

Principios base

• Nombres de recurso claros y coherentes (piensa en sustantivos).
• Comportamiento alineado con la semántica HTTP (leer vs escribir).
• Formas de respuesta parecidas entre rutas para que nadie adivine.
• Valores por defecto razonables y parámetros opcionales para filtrar u ordenar.

Checklist rápido

1. Rutas estables (el plural en recursos es una convención habitual).
2. Pocos códigos de estado usados de forma consistente.
3. Paginación documentada: qué significa “siguiente” o “anterior”.
4. Autenticación y permisos explícitos en la documentación.
5. Ejemplos del camino feliz y de errores típicos.

Cierre

Si priorizas la consistencia, la API se documenta sola, se testea mejor y cuesta menos adoptarla.