Cada integración con su propia autenticación
Una usa una clave en la configuración, otra un usuario de servicio y la tercera, un token que caducó sin que quedara registrado quién lo renovó.
Plataforma y operación
Capa de API e integraciones para plataformas de aprendizaje
Este diseño propone una pasarela para centralizar el gobierno y la seguridad de las API y observar el funcionamiento de las integraciones de Moodle.
El problema
El acceso técnico a servicios web no resuelve por sí solo el versionado, los permisos por consumidor, los límites de uso, la trazabilidad ni la experiencia de quienes integran.
Las API de un LMS rara vez coinciden con los contratos del negocio.
La matrícula, el progreso, el catálogo o la certificación significan cosas distintas para un LMS, un CRM, un HRIS y una aplicación corporativa. En la pasarela, defino contratos explícitos para esas diferencias, establezco qué datos conserva cada sistema y qué equipo responde de ellos, y evito que los equipos integradores dependan de la estructura interna de Moodle.
Decisión principal
Diseñar contratos estables que reflejen los límites de la plataforma.
La API debe expresar con claridad los casos de uso, la identidad, los errores y la idempotencia. También debe especificar qué operaciones siguen siendo asíncronas, qué datos quedan fuera del alcance de la pasarela, quién responde de ellos y qué cambios exigen una nueva versión del contrato.
Criterios de diseño
- 01
Defino una pasarela externa que expone casos de uso estables sin trasladar la estructura interna de Moodle a cada integración.
- 02
Normalizo los contratos de negocio y documento las limitaciones reales de la plataforma.
- 03
La identidad, los límites de uso, la caché, los eventos y la observabilidad forman parte del diseño inicial.
Límites del producto
La documentación de la pasarela deja claros los límites de la integración.
La pasarela no debe incorporar reglas de negocio que pertenecen a otros sistemas ni diseñarse o documentarse como si garantizara una consistencia inmediata que el flujo no puede ofrecer. Los eventos, la reconciliación y los registros de trazabilidad deben poder consultarse.
Capacidades previstas en el diseño
- 01API orientada a casos de uso
- 02Autenticación y ámbitos
- 03Límites de uso y caché
- 04Webhooks y portal técnico
Criterio de validación
La validación debe hacerse con varios sistemas que consuman la API.
El contrato se valida con escenarios de alta, actualización, duplicado, error parcial, reintento y revocación. Las pruebas deben demostrar que dos consumidores pueden evolucionar a ritmos distintos sin interrumpir la plataforma ni perder la trazabilidad.
Evidencia descrita para la capa de API e integraciones para plataformas de aprendizaje
- Arquitectura y contratos documentados
- Catálogo de casos de uso definido
- Estrategia de seguridad, observabilidad y versionado documentada
Preguntas abiertas
Decisiones pendientes en la capa de API e integraciones para plataformas de aprendizaje.
El alcance de la pasarela no debería ampliarse hasta que se hayan acordado la identidad de los consumidores, la política de versiones, el tratamiento de los errores y las garantías de entrega.
- Ámbito mínimo de la primera versión
- Modelo de extensiones
- Responsabilidad sobre datos derivados
- Adopción por equipos de integración
Contextos en los que encaja
Cuándo hace falta una capa por delante
Conviene valorarla cuando la repetición de autenticación, cuotas, observabilidad, versionado y políticas empieza a justificar su coste operativo.
Las dependencias no están inventariadas
Al plantear un cambio en la plataforma, no hay forma de saber qué sistemas externos dependen de ese dato.
Un sistema externo tumba la plataforma
Un proceso mal escrito consulta en bucle y el campus se degrada para todos, sin que exista un límite que lo pare.
Auditoría que pregunta quién accedió a qué
Y la respuesta hay que reconstruirla leyendo registros de cuatro sitios distintos.
Decisiones de arquitectura
Las decisiones que lleva dentro
Una pasarela añade una pieza al sistema: solo compensa si resuelve más de lo que complica.
- 01
Contratos explícitos por consumidor
Los consumidores comparten contratos de API versionados. Cada uno dispone de una política propia de ámbitos, cuotas y credenciales. Descarté una credencial global compartida y asigné una por consumidor, con ámbitos y rotación propios, para poder revocar sin afectar al resto.
- 02
Cuotas antes que confianza
Las cuotas acotan el impacto de un bucle o de un abuso. Sus umbrales se prueban con una carga representativa para comprobar qué degradación permiten y cómo responde el servicio.
- 03
Idempotencia de las operaciones reintentables que producen efectos
Cada comando repetible incorpora una clave o una regla que evita duplicados e impide repetir su efecto. Sin esta protección, un reintento en una red inestable puede crear matrículas fantasma.
- 04
Trazabilidad por operación, no por sistema
Cada llamada deja constancia de quién, qué y cuándo. Así, una auditoría puede responderse mediante consultas reproducibles en vez de reconstruir los accesos a mano.
A escala
Qué cambia con el número de integraciones
- Una o dos
El número por sí solo no suele justificar una pasarela: una conexión directa bien diseñada es más simple. Aun así, valoro la criticidad, la exposición, las cuotas, la auditoría, la tasa de cambio y el coste del gobierno común.
- Varias integraciones distintas
No decido solo por el número: mido criticidad, variedad de consumidores, tasa de cambio, exposición, requisitos de seguridad y coste de mantener contratos duplicados.
- Riesgo inaceptable sin gobierno común
La capa deja de ser opcional cuando las interfaces ya no pueden gobernarse ni cambiarse con un riesgo aceptable.
- Con datos personales de por medio
Defino la trazabilidad necesaria según la finalidad, el riesgo, los permisos y las obligaciones aplicables. El registro debe permitir investigar accesos relevantes sin recoger más datos de los necesarios.
Decisiones de diseño documentadas
Contratos de negocio que aíslan a los equipos de la estructura interna de Moodle
He definido casos de uso, identidad, versiones y errores para que los sistemas integradores puedan evolucionar sin depender de detalles internos de la plataforma.
- 01Arquitectura de plataforma
- 02Operación y observabilidad
- 03Gobierno técnico
- 04Integración con sistemas corporativos
Contexto profesional