REST API Design: 10 Principles for Clean APIs — cod-ai.com

Aún recuerdo el día en que tuve que explicar a nuestro CEO por qué nuestra aplicación móvil estaba consumiendo los planes de datos de los usuarios como un incendio forestal. Era 2016, y llevaba tres años en mi cargo como Arquitecto Principal de API en una startup fintech. Nuestra API REST estaba enviando de vuelta objetos de usuario enteros—completos con fotos de perfil codificadas en base64—cada vez que la aplicación consultaba los saldos de las cuentas. Estábamos perdiendo clientes, y yo había diseñado la API que nos estaba matando.

Lección dolorosa me enseñó algo crucial: el diseño de APIs REST no se trata solo de hacer que las cosas funcionen. Se trata de hacer que funcionen bien, a gran escala, en condiciones del mundo real que los libros de texto nunca mencionan. En los últimos doce años construyendo APIs para empresas que van desde startups de 10 personas hasta empresas de Fortune 500, he visto los mismos errores repetirse innumerables veces—y yo he cometido la mayoría de ellos.

Hoy, voy a compartir los diez principios que transformaron cómo diseño APIs. No son conceptos teóricos de trabajos académicos. Son pautas probadas en batalla forjadas en entornos de producción que sirven millones de solicitudes por día. Ya sea que estés construyendo tu primera API o refactorizando tu décima, estos principios te ayudarán a crear interfaces que los desarrolladores realmente quieran usar.

Principio 1: Diseña tu API como un Producto, No como un Wrapper de Base de Datos

El mayor error que veo en el diseño de APIs REST es tratar la API como una capa delgada sobre tablas de base de datos. He revisado cientos de APIs donde los endpoints se mapean uno a uno con esquemas de base de datos, exponiendo detalles de implementación interna que nunca deberían ver la luz del día. Este enfoque crea interfaces quebradizas que se rompen cada vez que tu modelo de datos evoluciona.

Cuando me uní a mi empresa actual como VP de Ingeniería de Plataforma, nuestra API tenía 47 endpoints que reflejaban directamente nuestro esquema de PostgreSQL. Cambiar un solo nombre de columna requería coordinar actualizaciones en 23 aplicaciones cliente diferentes. La deuda técnica estaba sofocando nuestra capacidad de innovar.

En lugar de eso, piensa en tu API como un producto con su propio ciclo de vida, estrategia de versionado y consideraciones de experiencia del usuario. A tus consumidores de API no les importa tu estrategia de normalización de base de datos o tu arquitectura interna de microservicios. Les importa cumplir tareas específicas de manera eficiente.

Por ejemplo, en lugar de exponer endpoints separados para /users, /user_profiles, /user_preferences y /user_settings, considera lo que realmente necesitan tus consumidores de API. En la mayoría de los casos, quieren un endpoint cohesivo /users/{id} que retorna un recurso compuesto de manera reflexiva. Usa parámetros de consulta como ?fields=profile,preferences para que los consumidores soliciten exactamente lo que necesitan.

Implementé este enfoque en una empresa de SaaS de salud donde reducimos nuestra superficie de API de 89 endpoints a 34 mientras realmente aumentábamos la funcionalidad. Los tiempos de respuesta cayeron un 43% porque eliminamos la necesidad de múltiples solicitudes para ensamblar información básica. Más importante aún, nuestra documentación de API se volvió comprensible, y el tiempo de incorporación de desarrolladores disminuyó de dos semanas a tres días.

La clave es entender el modelo de dominio de tu API, que puede diferir significativamente de tu modelo de persistencia. Dedica tiempo a tus consumidores de API—ya sean equipos frontend internos o socios externos—y comprende sus flujos de trabajo. Diseña recursos alrededor de sus modelos mentales, no de tus tablas de base de datos.

Principio 2: Acepta los Códigos de Estado HTTP Correctamente (Pero No los Sobrecargues)

Los códigos de estado HTTP son la primera línea de comunicación de tu API con los clientes, y aún así, constantemente los veo mal utilizados o ignorados por completo. Una vez audité una API que devolvía 200 OK para cada respuesta, incluidos errores, con el estado real enterrado en un campo JSON. Los desarrolladores pensaban que estaban siendo útiles al "tener siempre éxito", pero en realidad estaban rompiendo el manejo de errores de cada biblioteca de cliente HTTP.

No necesitas memorizar los 63 códigos de estado HTTP, pero debes usar correctamente los principales. Aquí tienes mi desglose práctico basado en doce años de experiencia en producción:

• 200 OK: GET, PUT o PATCH exitoso que devuelve contenido
• 201 Created: POST exitoso que crea un recurso (incluye encabezado Location)
• 204 No Content: DELETE exitoso o actualización que no devuelve nada
• 400 Bad Request: El cliente envió datos inválidos (incluye errores de validación específicos)
• 401 Unauthorized: Se requiere autenticación o ha fallado
• 403 Forbidden: Autenticado pero carece de permiso
• 404 Not Found: El recurso no existe
• 409 Conflict: La solicitud entra en conflicto con el estado actual (creación duplicada, desajuste de versión)
• 422 Unprocessable Entity: Sintácticamente correcto pero semánticamente inválido
• 429 Too Many Requests: Límite de tasa excedido (incluye encabezado Retry-After)
• 500 Internal Server Error: Algo se rompió de tu lado
• 503 Service Unavailable: Corte temporal o mantenimiento

La distinción entre 401 y 403 confunde a muchos desarrolladores. Piensa en 401 como "No sé quién eres" y 403 como "Sé quién eres, pero no puedes hacer eso." Esto importa porque le dice a los clientes si re-autenticarse podría ayudar.

De manera similar, 400 versus 422 es sutil pero útil. Usa 400 para JSON malformado o campos requeridos que faltan, cosas que fallan en un análisis básico. Usa 422 para violaciones de lógica de negocio, como intentar transferir más dinero del que existe en una cuenta. Esta distinción ayuda a los clientes a categorizar errores de manera apropiada.

En mi empresa anterior, implementamos un uso adecuado de códigos de estado y vimos que nuestros tickets de soporte relacionados con errores de API cayeron un 67% en el primer trimestre. Los desarrolladores finalmente pudieron confiar en la semántica estándar de HTTP en lugar de analizar los cuerpos de respuesta para determinar éxito o fracaso.

Principio 3: Versiona tu API Desde el Primer Día (Y Hazlo Bien)

Aprendí esta lección de la manera difícil. En 2014, lancé una API sin versionado porque "simplemente mantendremos la compatibilidad hacia atrás para siempre". Seis meses después, necesitábamos hacer un cambio disruptivo para soportar un requisito crítico del negocio. Teníamos 1,200 consumidores de API activos sin manera de migrarlos gradualmente. El resultado fue una actualización forzada que rompió