7 Errores de Diseño de REST API Que Te Acompañarán
Hace tres años, recibí una llamada a las 2 AM de un CTO cuya voz temblaba. Su base de datos de producción había sido borrada por completo. No había sido hackeada. No había un empleado descontento. Un rastreador web. Tenían un endpoint GET llamado `/api/users/cleanup` que se suponía debía devolver una lista de usuarios marcados para eliminación. Excepto que el desarrollador que lo construyó pensó que "cleanup" significaba "realizar limpieza" — así que el endpoint realmente eliminó a los usuarios cuando fue llamado. Un rastreador de motores de búsqueda descubrió este endpoint, lo indexó y lo golpeó 50,000 veces en una noche. Cada registro de usuario: desaparecido. El postmortem tomó tres días. La recuperación tomó dos semanas. ¿El daño reputacional? Aún se está calculando. He revisado más de 400 diseños de API para clientes empresariales en la última década. Mantengo una hoja de cálculo — sí, una hoja de cálculo real — de cada error de diseño que encuentro y su impacto en producción. Algunos errores cuestan horas. Algunos costaron millones. Todos ellos eran prevenibles. ¿La peor parte? No son casos extremos obscurecidos. Son decisiones de diseño fundamentales que parecen razonables en el momento, pero crean problemas en cascada que se acumulan con el tiempo. Son el tipo de errores que te hacen despertar a las 3 AM seis meses después de un lanzamiento, dándote cuenta de que te has encerrado en un rincón arquitectónico sin una salida limpia. Permíteme guiarte a través de los siete errores que veo con más frecuencia, por qué ocurren y cómo evitarlos antes de que atormenten tu entorno de producción.La Metodología Detrás de Estos Errores
Antes de sumergirnos en errores específicos, necesitas entender cómo categorizo los fallos en el diseño de API. No solo colecciono anécdotas — rastreo patrones a través de industrias, tamaños de equipos y pilas tecnológicas. Mi hoja de cálculo tiene 847 entradas hasta esta mañana. Cada entrada incluye la categoría de error, el tamaño del equipo, el tiempo hasta el descubrimiento (cuánto tardó hasta que alguien notó el problema), el tiempo para arreglarlo y el impacto comercial estimado. He anonimizado los datos, pero los patrones son claros. Los errores se dividen en tres niveles de severidad: Nivel 1: Molesto — Estos crean fricción para los consumidores de API, pero no rompen la funcionalidad. Piensa en convenciones de nomenclatura inconsistentes o documentación faltante. Tiempo promedio para solucionar: 2-4 horas. Impacto comercial promedio: baja satisfacción del desarrollador. Nivel 2: Costoso — Estos requieren una refactorización significativa o crean una carga de mantenimiento continuo. Piensa en estrategias de versionado pobres o endpoints excesivamente acoplados. Tiempo promedio para solucionar: 2-6 semanas. Impacto comercial promedio: retrasos en el lanzamiento de funciones, aumento de costos de soporte. Nivel 3: Catastrófico — Estos pueden causar pérdida de datos, violaciones de seguridad o interrupciones completas del servicio. Piensa en el endpoint GET que elimina datos o vulnerabilidades de elusión de autenticación. Tiempo promedio para solucionar: 1-3 meses (incluida la recuperación). Impacto comercial promedio: cifras de seis a siete dígitos. Los siete errores que cubro hoy abarcan los tres niveles. Algunos parecen menores hasta que estás lidiando con ellos a escala. Otros son obviamente peligrosos, pero sorprendentemente comunes. Lo que hace que estos errores sean particularmente insidiosos es que a menudo no emergen durante el desarrollo o incluso en la implementación inicial de producción. Surgen cuando alcanzas escala, cuando necesitas evolucionar la API o cuando consumidores externos comienzan a usar tus endpoints de formas que nunca anticipaste.La Historia Que Solo Yo Puedo Contar: El Desastre de la Paginación
Déjame contarte sobre el peor error de diseño de API que he presenciado personalmente — uno que le costó a una startup de Serie B su mayor acuerdo empresarial. La compañía construyó una API de gestión de proyectos. Limpia, bien documentada, rápida. Consiguieron una prueba piloto con una empresa Fortune 500 que quería migrar 15 años de datos de proyectos al nuevo sistema. El contrato valía 2.3 millones de dólares anuales. El equipo de migración comenzó a extraer datos a través del endpoint `/api/projects`. Todo funcionó perfectamente en las pruebas con su conjunto de datos de muestra de 500 proyectos. Luego lo ejecutaron contra producción: 340,000 proyectos. El endpoint usó paginación basada en offset: `/api/projects?offset=0&limit=100`. Cosas estándar. Excepto a escala, la paginación por offset tiene un defecto fatal: a medida que aumenta el offset, el rendimiento de la base de datos se degrada exponencialmente. ¿Recuperando los registros 0-100? Rápido. ¿Recuperando los registros 100,000-100,100? La base de datos tiene que escanear 100,000 registros solo para omitirlos. Para cuando llegaron al offset 300,000, cada solicitud estaba tardando 45 segundos y expirando. La migración que debería haber tomado 6 horas seguía funcionando después de 3 días. El equipo de infraestructura de la Fortune 500 lo marcó como un posible ataque DDoS. El CEO de la startup tuvo que llamar personalmente a su CTO para explicar que no, no los estaban atacando — su API estaba mal diseñada. Aquí está lo que hizo que fuera peor: arreglarlo requería un cambio disruptivo. Tuvieron que cambiar a paginación basada en cursor, lo que significaba que cada cliente tendría que actualizar su código de integración. La empresa Fortune 500 se retiró. No podían arriesgarse a construir sobre una API que requería cambios disruptivos durante una prueba piloto. Revisé su API seis meses después durante la debida diligencia para recaudar fondos de su Serie C. El problema de paginación seguía ahí. Tenían demasiado miedo de solucionarlo porque ahora tenían 40 clientes de pago que todos necesitarían actualizar su código. Esa es la cosa sobre los errores de diseño de API — se calcifican. Cuanto más tiempo existan, más difícil se vuelve arreglarlos. Cada nueva integración es otra razón por la que no puedes hacer cambios disruptivos.Los Datos: Lo Que Realmente Se Rompe en Producción
Analicé 400 revisiones de diseño de API que he realizado desde 2019. Aquí está lo que realmente causa problemas en producción:| Categoría de Error | Frecuencia | Tiempo Promedio hasta el Descubrimiento | Tiempo Promedio para Arreglar | ¿Se Requiere Cambio Disruptivo? |
|---|---|---|---|---|
| Estrategia de paginación deficiente | 67% | 4-8 meses | 6-12 semanas | Sí (89%) |
| Respuestas de error inconsistentes | 82% | 2-3 semanas | 3-6 semanas | No |
| Falta de limitación de tasa | 43% | 1-2 meses | 2-4 semanas | No |
| Operaciones no idempotentes | 38% | 3-6 meses | 8-16 semanas | Sí (72%) |
| Sobrefetching/subfetching | 91% | 1-3 meses | 4-8 semanas | A veces (45%) |
| Estrategia de versionado deficiente | 56% | 6-12 meses | 12-24 semanas | N/A (previene cambios futuros) |
| Métodos HTTP inseguros | 12% | 1-4 semanas | 1-2 semanas | Sí (100%) |
Por Qué Equipos Inteligentes Cometen Estos Errores
Aquí está lo que nadie te dice sobre el diseño de API: los errores no son causados por incompetencia. Son causados por decisiones razonables tomadas bajo restricciones que parecen sensatas en ese momento."Usamos paginación por offset porque eso es lo que el ORM nos dio por defecto. Cambiar a paginación basada en cursor habría agregado dos días al sprint, y ya estábamos retrasados. Pensamos que optimizaríamos más tarde si se convertía en un problema." — Líder de ingeniería en una startup de fintech, tres meses antes de que su paginación se convirtiera en un problemaEste es el patrón que veo repetidamente: los equipos toman la decisión más expedita porque están optimizando para enviar rápidamente, no para la mantenibilidad a largo plazo. Y en el momento, esa a menudo es la decisión comercial correcta. El problema es que "más tarde" nunca llega, o llega cuando arreglar el problema requiere cambios disruptivos que afectan a docenas de clientes. Otro patrón común: los equipos diseñan APIs basándose en sus modelos de datos internos en lugar de en las necesidades de sus consumidores. Tu base de datos tiene una tabla `users` con 47 columnas, así que tu endpoint `/api/users` devuelve todos los 47 campos. Parece lógico, ¿verdad? Excepto que tu aplicación móvil solo necesita 5 de esos campos, y ahora estás enviando 42 campos innecesarios a través de redes celulares a millones de dispositivos.
"Pensamos en filtrar campos, pero parecía una optimización prematura. Nuestros endpoints eran lo suficientemente rápidos en las pruebas. No nos dimos cuenta de que 'suficientemente rápido' con 100 usuarios de prueba se convierte en 'inaceptablemente lento' con 100,000 usuarios de producción." — CTO en una empresa SaaS, explicando por qué su aplicación móvil tenía un tiempo de carga de 4 segundosEl tercer patrón: los equipos no piensan en la evolución de la API. Diseñan la versión 1 sin considerar cómo manejarán la versión 2. No incluyen números de versión en las URLs o encabezados. No documentan qué campos son estables y cuáles podrían cambiar. Luego, seis meses después, necesitan hacer un cambio disruptivo y se dan cuenta de que no tienen una manera limpia de hacerlo sin romper integraciones existentes. Por eso siempre pregunto a los equipos durante las revisiones de diseño: "¿Qué pasa cuando necesiten cambiar esto?" Si la respuesta es "ya veremos entonces", te estás preparando para el dolor.
Cuestionando la Suposición de la "Pureza RESTful"
Aquí hay una opinión impopular: la estricta adhesión a los principios REST a menudo hace que las APIs sean peores, no mejores. Los puristas de REST te dirán que cada recurso debe tener exactamente una URL canónica, que debes usar los métodos HTTP de forma semántica, que tu API debe ser sin estado y cacheable y todas las demás restricciones que Roy Fielding esbozó en su disertación. ¿En la práctica? Algunas de las mejores APIs que he revisado violan los principios REST cuando tiene sentido para su caso de uso. Toma la API de GitHub. Tienen un endpoint llamado `/repos/{owner}/{repo}/commits` que devuelve commits. RESTful, ¿verdad? Pero también tienen `/search/commits` que devuelve... commits. Mismo recurso, estructura de URL diferente. ¿Por qué? Porque buscar commits es una operación fundamentalmente diferente a listar commits, y tratar de forzar la búsqueda en parámetros de consulta en la URL canónica crearía una peor experiencia para el desarrollador. O considera la API de Stripe. Usan POST para operaciones idempotentes que teóricamente deberían ser PUT. ¿Por qué? Porque POST es más ampliamente soportado por los clientes HTTP, y las claves de idempotencia en los encabezados proporcionan las mismas garantías que PUT sin los problemas de compatibilidad. El punto no es que REST sea malo — es que REST es un conjunto de directrices, no una doctrina religiosa. El objetivo es construir APIs que sean intuitivas, eficientes y mantenibles. A veces eso significa seguir los principios REST. A veces eso significa romperlos deliberadamente."Pasamos tres semanas discutiendo si nuestro endpoint de actualización masiva debería ser PUT o POST. En retrospectiva, deberíamos haber pasado esas tres semanas construyendo mejores mensajes de error. A nadie le importa la pureza del método HTTP cuando tu API devuelve '500 Internal Server Error' sin detalles." — Arquitecto de API en una empresa de salud