Intégrateurs

Cette section s'adresse aux développeurs qui connectent les workflows Mockomat à des systèmes d'ingénierie plus larges. Que tu construises un frontend qui consomme une API mock Mockomat, automatises la validation de modèle en CI/CD, ou intègres Mockomat dans le pipeline de développement de ton équipe, cette page couvre les patterns et pratiques dont tu as besoin.

Aperçu des endpoints API

Mockomat expose deux surfaces API distinctes :

API	Endpoint	Objectif	Authentification
API de gestion	GET /graphql	CRUD de projets, configuration de modèle, gestion des utilisateurs	JWT (basé sur la session)
API Mock Runtime	POST /mock/{slug}/graphql	Interroger les données mock, tester le comportement de domaine	Clé API + Token d'acteur (Business+) ou public (Free/Quick)

L'API de gestion est utilisée par l'application web Mockomat et les outils d'administration. L'API mock runtime est ce que tes applications consomment comme backend mock.

Patterns d'authentification

Les exigences d'authentification dépendent de ton forfait et du type d'endpoint.

Endpoints publics (Quick et Free)

Les endpoints publics ne nécessitent aucune authentification. Tout client HTTP peut envoyer des requêtes :

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

Les endpoints publics sont limités en débit par adresse IP pour prévenir les abus.

Endpoints privés (Business et Enterprise)

Les endpoints privés nécessitent deux en-têtes d'authentification :

En-tête	Valeur	Objectif
Authorization	Bearer <API_KEY>	Identifie le projet et autorise l'accès
X-Actor-Token	<ACTOR_TOKEN>	Identifie le consommateur pour le suivi de concurrence

Authentification par clé API

Les clés API sont émises par projet dans le workspace Mockomat. Chaque clé :

• Est scopée à un seul projet
• Peut être renouvelée sans affecter les autres clés
• A ses propres limites de concurrence et de débit
• Peut être révoquée à tout moment

Workflow des tokens d'acteur

Les tokens d'acteur gèrent les consommateurs API concurrents. Le workflow :

1. Demander un token — appelle l'endpoint des acteurs avec ta clé API :

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

Réponse :

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

2. Utiliser le token — inclus-le dans toutes les requêtes runtime suivantes :

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. Expiration du token — les tokens d'acteur ont un timeout d'inactivité configurable (15 minutes par défaut). Chaque requête renouvelle le timeout. Si le token expire, demands-en un nouveau.

int-01-authenticationMissing

Point d'entrée d'intégration avec configuration de l'authentification et du contexte.

Patterns de requêtes

Requête de liste basique

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

Requête de détail

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

Requête avec filtrage

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

Requête triée et paginée

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

Requête avec relations imbriquées

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

Flux d'intégration recommandé

1. Définir un périmètre de domaine stable

Avant d'intégrer, identifie quelles entités et requêtes ton application va consommer. N'intègre pas contre un modèle qui change encore fréquemment — attends que la structure principale soit stable.

2. Verrouiller le nommage et les contrats de champs

Traite le schéma GraphQL comme un contrat. Une fois que ton application dépend de noms de requêtes et de structures de champs spécifiques, les changements de ces noms casseront l'intégration. Utilise la vue de conception API dans Mockomat pour finaliser les noms de requêtes avant de connecter les consommateurs.

3. Valider le comportement runtime

Exécute des requêtes complètes via la prévisualisation runtime et vérifie :

• Les types de champs correspondent à ce que ton application attend
• L'imbrication des relations fonctionne correctement
• Les filtres retournent les sous-ensembles attendus
• La pagination produit des transitions de page propres

4. Intégrer les systèmes consommateurs

Connecte ton application frontend, suite de tests ou autres consommateurs à l'endpoint mock. Utilise des variables d'environnement ou des fichiers de configuration pour basculer entre les endpoints Mockomat et les vrais backends :

// environment.ts
export const environment = {
  apiUrl: 'https://api.mockomat.com/mock/my-project/graphql',
  // Basculer vers le vrai backend quand prêt :
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Promouvoir vers l'export/implémentation

Lorsque le contrat d'API mock est stable et que ton frontend fonctionne correctement contre celui-ci, utilise la fonctionnalité d'Export pour générer un backend de production qui implémente le même contrat.

int-02-ci-cd-flowMissing

Pattern d'intégration CI/CD avec points de contrôle modèle et runtime.

CI/CD et automatisation

Les APIs mock Mockomat peuvent être intégrées dans ton pipeline CI/CD pour valider le comportement frontend contre un backend mock stable.

Patterns d'intégration pipeline

Validation de contrat — exécute des vérifications de comparaison de schéma lors des changements de modèle pour détecter les changements cassants avant qu'ils n'atteignent les consommateurs.

Tests d'intégration — pointe ta suite de tests d'intégration vers l'endpoint Mockomat pour vérifier le comportement frontend contre des données mock réalistes.

Validation de prévisualisation — avant de merger les changements de modèle, valide que le runtime produit les résultats attendus en interrogeant l'endpoint de prévisualisation de manière programmatique.

Exemple d'étapes de pipeline

# Exemple d'étape 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: |
      # Récupérer le schéma actuel et comparer à 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

Versionnage des artefacts générés

Lors de l'utilisation de la fonctionnalité d'export, versionne le code backend généré aux côtés de ton application :

• Commite le code généré dans une branche ou un dépôt dédié.
• Tague les exports avec la version du modèle ou la date.
• Inclus un changelog résumant les changements de modèle depuis le dernier export.
• Révise les diffs du code généré avant de merger dans la branche principale.

Limitation de débit

Mockomat applique une limitation de débit à plusieurs niveaux pour garantir une utilisation équitable et la stabilité de la plateforme.

Périmètre	Free/Quick	Business	Enterprise
Par IP	60 req/min	N/A	N/A
Par clé API	N/A	Selon le forfait	Personnalisé
Par tenant	N/A	N/A	Configurable

Lorsqu'une limite de débit est atteinte, l'API retourne HTTP 429 (Too Many Requests) avec un en-tête Retry-After indiquant combien de temps attendre avant de réessayer.

Gestion des erreurs

Réponses d'erreur courantes et comment les gérer :

Statut HTTP	Code d'erreur	Signification	Action
400	INVALID_QUERY	Erreur de syntaxe de requête GraphQL	Vérifier la syntaxe de la requête
401	UNAUTHORIZED	Clé API manquante ou invalide	Vérifier l'en-tête de la clé API
401	SESSION_EXPIRED	Le token d'acteur a expiré	Demander un nouveau token d'acteur
403	MAX_TENANT_SESSIONS_REACHED	Limite de sessions concurrentes atteinte	Attendre qu'une session expire ou en libérer une
404	PROJECT_NOT_FOUND	Slug de projet invalide	Vérifier l'URL de l'endpoint
429	RATE_LIMITED	Trop de requêtes	Attendre la durée indiquée par Retry-After
429	MAX_ACTIVE_ACTORS_REACHED	Limite d'acteurs concurrents atteinte	Attendre qu'un acteur expire

Format de réponse d'erreur

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

Vérifie toujours le champ retryAfterSeconds lorsqu'il est disponible — il indique le temps d'attente minimum avant de réessayer.

Observabilité et diagnostics

Suis ces signaux clés à travers les environnements pour maintenir la fiabilité de l'intégration :

Métriques clés

• Stabilité des requêtes — les réponses sont-elles structurées de manière cohérente ? Surveille les changements de schéma inattendus.
• Dérive de la forme des réponses — les types de champs ou les niveaux d'imbrication changent-ils entre les mises à jour du modèle ?
• Fiabilité des lookups de relations — les requêtes imbriquées se résolvent-elles systématiquement correctement ?
• Patterns d'erreurs et de timeouts — certaines requêtes sont-elles systématiquement lentes ou en échec ?
• Proximité des limites de débit — à quel point es-te proche d'atteindre les limites de requêtes ou de concurrence ?

Recommandations de surveillance

• Journalise toutes les réponses API (ou au minimum les codes de statut et temps de réponse) dans ton application consommatrice.
• Configure des alertes pour les réponses HTTP 429 et 401 — elles indiquent des problèmes de configuration ou de capacité.
• Compare périodiquement les schémas de réponse à une baseline pour détecter les dérives non intentionnelles.
• Surveille les patterns de renouvellement des tokens d'acteur pour optimiser ta stratégie de concurrence.

int-03-observabilityMissing

Points de contrôle d'observabilité pour la fiabilité de l'intégration.

Bonne pratique

Developer / Integrator

Traite les artefacts Mockomat comme des actifs contract-first. Maintiens l'intention du modèle, le comportement runtime et les décisions d'implémentation traçables dans le même ensemble de changements. Lorsque ton frontend dépend d'une forme de requête spécifique, documente cette dépendance et valide-la en CI.

Note d'intégration Enterprise

Enterprise User

Pour les environnements Enterprise, utilise des clés API séparées par environnement (développement, staging, production). Cela te permet de suivre l'utilisation par environnement et de renouveler les clés indépendamment. Combine avec les tokens d'acteur pour contrôler exactement combien de consommateurs concurrents chaque environnement supporte.