Principios de diseño de APIs REST que resisten el paso del tiempo

Las grandes APIs se sienten aburridas de la mejor manera: predecibles, consistentes y fáciles de razonar. Cuando la superficie es simple, los equipos entregan más rápido y los clientes se rompen con menos frecuencia.

Esta es una lista ligera que puedes tener en mente al diseñar nuevos endpoints o al revisar una API existente.

Principios clave

• Usa nombres de recursos claros y consistentes (piensa en sustantivos).
• Mantén el comportamiento alineado con la semántica HTTP (lectura vs escritura).
• Devuelve formas de respuesta consistentes para que los clientes no tengan que adivinar.
• Prefiere valores predeterminados sensatos con parámetros de consulta opcionales para filtrar/ordenar.

Una lista simple

1. Elige rutas de recursos estables (los sustantivos en plural son una convención común).
2. Usa un conjunto pequeño de códigos de estado de forma consistente.
3. Documenta la paginación y qué significan “siguiente/anterior”.
4. Sé explícito sobre los requisitos de autenticación y autorización.
5. Agrega ejemplos breves en la documentación para el “camino feliz” y los errores comunes.

Cierre

Si primero optimizas por consistencia, tu API será más fácil de documentar, más fácil de probar y más fácil de adoptar para otros.