Cuatro lecciones de integración de APIs empresariales que todo desarrollador debería conocer
Hay un momento en todo proyecto de integración donde el desarrollador mira la documentación oficial de la API, la ve limpia y bien estructurada, y piensa: "esto va a ser sencillo". Unas horas después, está depurando respuestas inconsistentes, paginación que varía por endpoint y autenticaciones que funcionan diferente según el tipo de usuario. Bienvenido al mundo real de las APIs empresariales.
El equipo detrás del productor OSIRIS JSON para HPE Aruba Networking Central publicó esta semana un artículo técnico que documenta con honestidad cuatro problemas concretos que tuvieron que resolver al construir un colector de infraestructura de red en Go. Más allá del contexto específico de Aruba Central, cada uno de estos problemas refleja patrones que aparecen una y otra vez en integraciones con APIs de proveedores enterprise — y las soluciones tienen implicaciones directas para cualquier equipo técnico en Perú y América Latina que construya sobre plataformas de terceros.
En este artículo analizamos los cuatro casos, qué los hace peligrosos, y qué principios de diseño se pueden extraer para aplicarlos en proyectos propios.
1. La paginación no es un comportamiento global — es una decisión por endpoint
El primer instinto al construir un cliente de API es centralizar la lógica de paginación: un solo método que llama repetidamente hasta agotar los resultados. Es limpio, reutilizable y elegante. El problema es que asume que todos los endpoints de la API paginan igual.
En Aruba Central, esa suposición es incorrecta. Algunos endpoints usan paginación por limit y offset y aceptan hasta 1000 items por llamada. Otros usan paginación por cursor. Otros tienen un tamaño máximo de página más pequeño y devuelven un error 400 si se excede. Si el cliente no distingue entre estos casos, puede terminar en un estado peligroso: la colección parece exitosa pero los datos están incompletos.
Para infraestructura de red, esto es crítico. Un inventario que silenciosamente omite dispositivos es más dañino que un error visible, porque los sistemas downstream asumen que el snapshot es completo. La solución del equipo fue simple pero poderosa: hacer la estrategia de paginación explícita, testeable e imposible de ignorar a nivel de cada recurso.
Este principio aplica directamente a cualquier integración con ERPs, plataformas de e-commerce, sistemas bancarios o APIs de gobierno. Antes de asumir uniformidad, hay que mapear el comportamiento real de cada endpoint crítico.
2. Parsing tolerante con identidad estricta: cómo manejar respuestas inconsistentes sin perder integridad
El endpoint de vecinos LLDP/CDP de Aruba Central — el que permite construir el mapa de relaciones entre dispositivos de red — tiene un comportamiento inusual: dependiendo del contexto, la respuesta puede llegar como un array directo o como un objeto con estructura diferente. No hay un envelope consistente como {"items": [...]}.
La solución fue implementar un parser tolerante: código que acepta las formas observadas en la práctica, no solo las documentadas, pero que mantiene validación estricta sobre los datos necesarios para construir una relación válida. Esto es diferente a simplemente aceptar cualquier cosa — es ser flexible en el formato pero riguroso en el significado.
Adicionalmente, el endpoint mezcla tipos de entidades (clientes, registros de stack) que ya existen en otros modelos. Incluirlos sin filtrar generaría duplicados y relaciones ambiguas. El equipo filtró esas clases pero preservó deliberadamente los vecinos no administrados — dispositivos externos con seriales sintéticos — porque registrar que una relación existe tiene valor, incluso cuando se sabe poco del dispositivo en el otro extremo.
Este enfoque — tolerante en formato, estricto en identidad — es un patrón maduro para cualquier integración donde la fuente de datos no está completamente bajo tu control.
3. El modelo de API no siempre refleja el hardware — refleja el modelo operativo del fabricante
Los switch stacks de Aruba Central introdujeron un problema de una categoría diferente. Cuando se consultan detalles de hardware o interfaces de un miembro no conductor del stack, la API devuelve 404. El conductor es el único punto de consulta válido, y su respuesta incluye datos de todos los miembros físicos del stack.
Esto obligó a cambiar el patrón de colección: en lugar de iterar dispositivo por dispositivo, hay que primero identificar al conductor, consultarlo una sola vez, y luego enrutar cada interfaz de vuelta al switch correcto por número de serie en memoria. Esto evita llamadas redundantes y previene que las interfaces de miembros individuales se asignen incorrectamente al stack como un objeto único.
La lección más amplia es importante: los recursos de una API no siempre mapean uno a uno con los recursos físicos de infraestructura. Un colector tiene que entender el modelo operativo detrás del endpoint, no solo su contrato HTTP. Esto es especialmente relevante para equipos que integran plataformas de networking, telefonía o manufactura, donde el software del fabricante tiene su propia abstracción del hardware.
¿Cómo aplica esto en tu empresa?
Si tu equipo está construyendo integraciones con APIs de proveedores enterprise — ya sea para conectar un ERP con sistemas externos, consumir APIs de plataformas de networking, o automatizar colecciones de datos de infraestructura — estos cuatro casos ofrecen un checklist práctico:
- Mapea la paginación por endpoint, no por API. Antes de construir el cliente genérico, prueba manualmente cada endpoint crítico con diferentes tamaños de página.
- Implementa parsers tolerantes para fuentes que no controlas. Si la API del proveedor puede cambiar el formato de respuesta sin aviso, tu parser debe sobrevivir eso sin fallar silenciosamente.
- Entiende el modelo operativo, no solo el contrato HTTP. La documentación oficial describe el contrato. La realidad de producción puede requerir entender cómo el proveedor modela su infraestructura internamente.
- Soporta múltiples flujos de autenticación desde el diseño. Enterprise y self-service tienen necesidades diferentes. La lógica de colección debe ser idéntica independientemente de cómo se obtuvo el token.
- Prefiere el error visible al éxito silencioso con datos incompletos. En integraciones críticas, un fallo que se detecta es siempre mejor que datos parciales que parecen completos.
En proyectos de integración con Odoo y sistemas externos que hemos desarrollado en Consultoría-Ti, estos mismos patrones aparecen constantemente. La diferencia entre una integración frágil y una robusta no está en la tecnología elegida — está en cuánto se invirtió en entender el comportamiento real de la API antes de escribir la primera línea de código de negocio.
Conclusión
El artículo de Tia Zanella sobre el productor OSIRIS JSON para Aruba Central es un ejemplo valioso de documentación técnica honesta: no solo muestra qué se construyó, sino qué salió mal en el camino y por qué las soluciones tomaron la forma que tomaron. Eso es más útil que cualquier tutorial de "happy path".
Para equipos técnicos en Perú y América Latina que trabajan con integraciones enterprise, la pregunta no es si van a encontrar estos problemas — es cuándo. Tener estos patrones documentados y en el radar antes de comenzar puede ahorrar semanas de debugging en producción.
Si tu empresa está enfrentando un proyecto de integración complejo — con APIs de terceros, plataformas de infraestructura, o sistemas ERP — en Consultoría-Ti podemos ayudarte a diseñar una arquitectura de integración robusta desde el inicio. Conversemos sobre tu proyecto.
Fuentes y Referencias
Tia Zanella — Building an Aruba Central Producer in Go: Four API edge cases we had to solve (Dev.to)
✨ Contenido generado con ContentFlow — Consultoría-Ti