Qué hace buena a una API

Antes de seguir, pongámonos de acuerdo en qué estamos intentando construir. La comunidad de diseño de APIs —desde los principios REST de Roy Fielding hasta las guías modernas de Stripe, Twilio y GitHub— ha convergido en unos pocos principios centrales. No son opiniones arbitrarias: son lecciones de miles de millones de peticiones servidas en producción, de APIs que escalaron con suavidad y de APIs que se hundieron bajo su propia complejidad.

Una buena API no es sólo una que funciona. Es una que:

1. Hace una cosa bien. Tu API debería tener un propósito claro. Una API de gestión de licencias no debería registrar dominios. Una API de pagos no debería gestionar perfiles de usuario. Este principio —el de responsabilidad única— se aplica a servicios enteros. Cuando una API intenta hacerlo todo, no hace nada bien. Stripe, GitHub y Twilio están enfocadísimos en su dominio. Hacen una cosa y la hacen de forma brillante.

2. Es predecible. Las respuestas deben seguir patrones consistentes. Los errores deben estructurarse igual. Los nombres de campo deben ser coherentes. Cuando llamas a GET /licenses, la estructura de la respuesta debería casar con la de POST /license. Tu API es un contrato con quien la consume; Stripe lo llama «consistencia». Rómpelo y pierden la confianza. Mantenlo y construirán sobre tu API con seguridad.

3. Es segura por defecto. La seguridad no debería ser una ocurrencia tardía. Las cabeceras CORS deberían ser restrictivas por defecto. El límite de frecuencia te protege del abuso. La autenticación debería ser obligatoria en las rutas protegidas. Construye la seguridad en los cimientos, no atornillada después. El OWASP API Security Top 10 es claro: la mayoría de las vulnerabilidades vienen de autenticación rota, autorización rota y exposición excesiva de datos. Son fallos de arquitectura, no de criptografía.

4. Falla con elegancia. Las redes fallan. Las bases de datos se caen. Los usuarios envían datos malformados. Devuelve códigos HTTP con significado (no todo es 200 o 500). Da detalles de error que ayuden a entender qué pasó. Stripe documenta con precisión qué significa cada código y ofrece códigos de error para manejo programático. No necesitas claves de idempotencia el primer día, pero nunca devuelvas un 500 críptico cuando puedes dar información real.

5. Es observable. Cuando algo va mal en producción —y va a ir mal— deberías enterarte de inmediato. Usa registro estructurado. Usa identificadores de petición para trazar operaciones por tu sistema. Usa métricas para vigilar velocidad y fallos. Si no puedes ver tu sistema, no puedes arreglarlo.

6. Puede evolucionar. Tu API no está terminada el primer día. Crece y se adapta. Diseña para la evolución: versiona con cuidado, avisa de las deprecaciones, piensa en cómo los campos nuevos no romperán a los consumidores existentes. Tu API no servirá las mismas peticiones dentro de tres años. Diseña sabiéndolo.

Estos principios no son exclusivos de este libro. Están enraizados en décadas de experiencia en el sector. Lo que este libro hace es enseñarte a construirlos dentro de tu aplicación Laravel desde el principio.