Integradores

Esta sección está dirigida a desarrolladores que conectan los flujos de trabajo de Mockomat con sistemas de ingeniería más amplios. Ya sea que estés construyendo un frontend que consume una API mock de Mockomat, automatizando la validación de modelos en CI/CD, o integrando Mockomat en el pipeline de desarrollo de tu equipo, esta página cubre los patrones y prácticas que necesitas.

Resumen de endpoints API

Mockomat expone dos superficies API distintas:

API	Endpoint	Propósito	Autenticación
API de gestión	GET /graphql	CRUD de proyectos, configuración de modelo, gestión de usuarios	JWT (basado en sesión)
API Mock Runtime	POST /mock/{slug}/graphql	Consultar datos mock, probar comportamiento de dominio	Clave API + Token de actor (Business+) o público (Free/Quick)

La API de gestión es utilizada por la aplicación web de Mockomat y las herramientas administrativas. La API mock runtime es lo que tus aplicaciones consumen como backend mock.

Patrones de autenticación

Los requisitos de autenticación dependen de tu plan y tipo de endpoint.

Endpoints públicos (Quick y Free)

Los endpoints públicos no requieren autenticación. Cualquier cliente HTTP puede enviar consultas:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(limit: 10) { id name price } }"}'

Los endpoints públicos tienen limitación de tasa por dirección IP para prevenir abusos.

Endpoints privados (Business y Enterprise)

Los endpoints privados requieren dos cabeceras de autenticación:

Cabecera	Valor	Propósito
Authorization	Bearer <API_KEY>	Identifica el proyecto y autoriza el acceso
X-Actor-Token	<ACTOR_TOKEN>	Identifica al consumidor para seguimiento de concurrencia

Autenticación por clave API

Las claves API se emiten por proyecto en el workspace de Mockomat. Cada clave:

• Tiene alcance a un solo proyecto
• Puede rotarse sin afectar otras claves
• Tiene sus propios límites de concurrencia y tasa
• Puede revocarse en cualquier momento

Flujo de trabajo de tokens de actor

Los tokens de actor gestionan los consumidores API concurrentes. El flujo:

1. Solicitar un token — llama al endpoint de actores con tu clave API:

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json"

Respuesta:

{
  "actorToken": "act_abc123...",
  "expiresInSeconds": 900,
  "maxActors": 5,
  "currentActors": 2
}

2. Usar el token — inclúyelo en todas las solicitudes runtime subsiguientes:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(limit: 10) { id name price } }"}'

3. Expiración del token — los tokens de actor tienen un timeout de inactividad configurable (15 minutos por defecto). Cada solicitud renueva el timeout. Si el token expira, solicita uno nuevo.

int-01-authenticationMissing

Punto de entrada de integración con configuración de autenticación y contexto.

Patrones de consultas

Consulta de lista básica

query {
  products(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Consulta de detalle

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Consulta con filtrado

query {
  products(
    filter: {
      filterGroup: {
        operator: AND
        items: [
          { attribute: "price", operator: GE, value: "10" }
          { attribute: "category", operator: EQ, value: "electronics" }
        ]
      }
    }
    limit: 50
  ) {
    id
    name
    price
  }
}

Consulta ordenada y paginada

query {
  products(
    sort: { field: "price", direction: ASC }
    offset: 20
    limit: 20
  ) {
    id
    name
    price
  }
}

Consulta con relaciones anidadas

query {
  customers(limit: 10) {
    id
    firstName
    lastName
    orders {
      id
      totalAmount
      createdAt
      items {
        id
        productName
        quantity
        unitPrice
      }
    }
  }
}

Flujo de integración recomendado

1. Definir un alcance de dominio estable

Antes de integrar, identifica qué entidades y consultas tu aplicación consumirá. No integres contra un modelo que aún cambia frecuentemente — espera hasta que la estructura principal sea estable.

2. Fijar nombrado y contratos de campos

Trata el esquema GraphQL como un contrato. Una vez que tu aplicación depende de nombres de consultas y estructuras de campos específicos, los cambios en esos nombres romperán la integración. Usa la vista de diseño API en Mockomat para finalizar nombres de consultas antes de conectar consumidores.

3. Validar el comportamiento runtime

Ejecuta consultas completas a través de la previsualización runtime y verifica:

• Los tipos de campos coinciden con lo que tu aplicación espera
• El anidamiento de relaciones funciona correctamente
• Los filtros devuelven los subconjuntos esperados
• La paginación produce transiciones de página limpias

4. Integrar sistemas consumidores

Conecta tu aplicación frontend, suite de pruebas u otros consumidores al endpoint mock. Usa variables de entorno o archivos de configuración para cambiar entre endpoints de Mockomat y backends reales:

// environment.ts
export const environment = {
  apiUrl: 'https://api.mockomat.com/mock/my-project/graphql',
  // Cambiar al backend real cuando esté listo:
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Promover a exportación/implementación

Cuando el contrato de API mock es estable y tu frontend funciona correctamente contra él, usa la funcionalidad de Exportación para generar un backend de producción que implemente el mismo contrato.

int-02-ci-cd-flowMissing

Patrón de integración CI/CD con puntos de control de modelo y runtime.

CI/CD y automatización

Las APIs mock de Mockomat pueden integrarse en tu pipeline CI/CD para validar el comportamiento frontend contra un backend mock estable.

Patrones de integración en pipeline

Validación de contrato — ejecuta verificaciones de comparación de esquema cuando los modelos cambian para detectar cambios que rompan antes de que lleguen a los consumidores.

Pruebas de integración — apunta tu suite de pruebas de integración al endpoint de Mockomat para verificar el comportamiento frontend contra datos mock realistas.

Validación de previsualización — antes de hacer merge de cambios de modelo, valida que el runtime produce los resultados esperados consultando el endpoint de previsualización programáticamente.

Ejemplo de pasos de pipeline

# Ejemplo de paso de pipeline CI
steps:
  - name: Run integration tests against mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: npm run test:integration

  - name: Validate schema contract
    run: |
      # Obtener el esquema actual y comparar con la baseline
      curl -s $API_URL -d '{"query":"{ __schema { types { name } } }"}' \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" > current-schema.json
      diff baseline-schema.json current-schema.json

Versionado de artefactos generados

Al usar la funcionalidad de exportación, versione el código backend generado junto con tu aplicación:

• Haz commit del código generado en una rama o repositorio dedicado.
• Etiqueta las exportaciones con la versión del modelo o la fecha.
• Incluya un changelog resumiendo los cambios de modelo desde la última exportación.
• Revisa los diffs del código generado antes de hacer merge a la rama principal.

Limitación de tasa

Mockomat aplica limitación de tasa en múltiples niveles para asegurar un uso equitativo y la estabilidad de la plataforma.

Alcance	Free/Quick	Business	Enterprise
Por IP	60 req/min	N/A	N/A
Por clave API	N/A	Según el plan	Personalizado
Por tenant	N/A	N/A	Configurable

Cuando se alcanza el límite de tasa, la API devuelve HTTP 429 (Too Many Requests) con una cabecera Retry-After indicando cuánto tiempo esperar antes de reintentar.

Gestión de errores

Respuestas de error comunes y cómo manejarlas:

Estado HTTP	Código de error	Significado	Acción
400	INVALID_QUERY	Error de sintaxis de consulta GraphQL	Verificar la sintaxis de la consulta
401	UNAUTHORIZED	Clave API faltante o inválida	Verificar la cabecera de clave API
401	SESSION_EXPIRED	El token de actor ha expirado	Solicitar un nuevo token de actor
403	MAX_TENANT_SESSIONS_REACHED	Límite de sesiones concurrentes alcanzado	Esperar a que una sesión expire o liberar una
404	PROJECT_NOT_FOUND	Slug de proyecto inválido	Verificar la URL del endpoint
429	RATE_LIMITED	Demasiadas solicitudes	Esperar la duración de Retry-After
429	MAX_ACTIVE_ACTORS_REACHED	Límite de actores concurrentes alcanzado	Esperar a que un actor expire

Formato de respuesta de error

{
  "error": "MAX_ACTIVE_ACTORS_REACHED",
  "maxActors": 5,
  "currentActors": 5,
  "retryAfterSeconds": 342
}

Siempre verifica el campo retryAfterSeconds cuando esté disponible — indica el tiempo mínimo de espera antes de reintentar.

Observabilidad y diagnósticos

Sigue estas señales clave a través de los entornos para mantener la fiabilidad de la integración:

Métricas clave

• Estabilidad de consultas — ¿las respuestas están estructuradas de manera consistente? Vigila los cambios de esquema inesperados.
• Deriva de la forma de respuesta — ¿los tipos de campos o niveles de anidamiento cambian entre actualizaciones del modelo?
• Fiabilidad de lookups de relación — ¿las consultas anidadas se resuelven sistemáticamente de forma correcta?
• Patrones de errores y timeouts — ¿algunas consultas son sistemáticamente lentas o fallan?
• Proximidad de límites de tasa — ¿qué tan cerca está de alcanzar los límites de solicitudes o concurrencia?

Recomendaciones de monitoreo

• Registra todas las respuestas API (o al menos los códigos de estado y tiempos de respuesta) en tu aplicación consumidora.
• Configura alertas para respuestas HTTP 429 y 401 — indican problemas de configuración o capacidad.
• Compara periódicamente los esquemas de respuesta contra una baseline para detectar derivas no intencionales.
• Monitorea los patrones de renovación de tokens de actor para optimizar tu estrategia de concurrencia.

int-03-observabilityMissing

Puntos de control de observabilidad para la fiabilidad de la integración.

Buena práctica

Developer / Integrator

Trata los artefactos de Mockomat como activos contract-first. Mantén la intención del modelo, el comportamiento runtime y las decisiones de implementación trazables en el mismo conjunto de cambios. Cuando tu frontend dependa de una forma de consulta específica, documenta esa dependencia y valídela en CI.

Nota de integración Enterprise

Enterprise User

Para entornos Enterprise, usa claves API separadas por entorno (desarrollo, staging, producción). Esto te permite seguir el uso por entorno y rotar claves independientemente. Combina con tokens de actor para controlar exactamente cuántos consumidores concurrentes soporta cada entorno.