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 (Authorization: Bearer mck_…) ; projets invités : token de partage

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.

Authentification

Chaque requête à l'API mock runtime d'un projet de ton compte porte une clé API. Les requêtes sans clé valide sont refusées, quel que soit le réglage de partage de l'aperçu du projet — un lien de partage ouvre la page d'aperçu, pas l'API.

Clés API

Tu crées les clés dans l'application sous Compte → Clés API, pour le projet actif. Les clés API sont incluses à partir du forfait Professional. Chaque clé :

• Appartient à un seul projet et ne répond que pour ce projet
• N'est affichée en entier qu'une seule fois, à sa création — conserve-la comme un mot de passe
• Peut avoir une date d'expiration et être révoquée à tout moment
• A un scope : Runtime interroge les données mock, Full atteint aussi l'API de gestion ; une clé Management ne peut pas interroger le runtime

Envoie la clé comme bearer token :

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

L'en-tête X-API-Key: mck_your_api_key fonctionne aussi.

Garde la clé hors du code navigateur

Une clé API est un secret. Appelle l'API mock depuis du code côté serveur, depuis ta CI ou via un proxy de serveur de développement qui ajoute l'en-tête (étape 4 du flux d'intégration ci-dessous) — ne livre jamais la clé dans un bundle frontend.

Projets invités

Un projet invité (sans compte) n'a pas de clés API. Son endpoint accepte le token de partage du projet — celui de son lien de partage d'aperçu — en paramètre de requête :

curl -X POST "https://api.mockomat.com/mock/my-guest-project/graphql?token=<share-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name } total } }"}'

Les requêtes invitées sont décomptées du quota quotidien de la session invitée.

Tokens d'acteur (optionnels)

Les tokens d'acteur distinguent les consommateurs d'une même clé API, afin de pouvoir plafonner l'utilisation simultanée d'une clé. Ils sont optionnels — une requête avec la seule clé API est servie.

1. Demander un token avec ta clé API :

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer mck_your_api_key"

Réponse :

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

2. L'envoyer avec tes requêtes runtime :

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

3. Expiration par inactivité — un token expire après 15 minutes sans requête ; chaque requête le prolonge. Tant que tous les emplacements d'acteur d'une clé sont occupés, un nouvel acteur reçoit 429 MAX_ACTIVE_ACTORS_REACHED avec un en-tête Retry-After.

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(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

Requête de détail

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

Requête avec filtrage

Les arguments sont des paramètres que l'opération définit dans la conception API (ici minPrice sur price avec gte, category avec eq) ; voir le Runtime pour les opérateurs, la recherche et la pagination.

query {
  products(minPrice: 10, category: "electronics", pageSize: 50) {
    items {
      id
      name
      price
    }
    total
  }
}

Requête triée et paginée

query {
  products(sortField: "price", sortDirection: ASC, page: 2, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

Requête avec relations imbriquées

query {
  customers(pageSize: 10) {
    items {
      id
      firstName
      lastName
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

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 ta suite de tests, ton backend-for-frontend ou d'autres consommateurs à l'endpoint mock. Garde l'endpoint et la clé API dans la configuration, pour pouvoir basculer entre Mockomat et ton vrai backend.

Une application frontend atteint l'API mock via le proxy de son serveur de développement, qui ajoute la clé côté serveur — la clé ne finit donc jamais dans le bundle :

// vite.config.ts — transmet /mock-api à Mockomat et ajoute la clé API
export default defineConfig({
  server: {
    proxy: {
      '/mock-api': {
        target: 'https://api.mockomat.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/mock-api/, '/mock/my-project'),
        headers: { Authorization: `Bearer ${process.env.MOCKOMAT_API_KEY}` },
      },
    },
  },
});

// environment.ts — l'application ne connaît que le chemin du proxy
export const environment = {
  apiUrl: '/mock-api/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: Smoke-check the mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: |
      # Fait échouer l'étape sur 401/403/404 : clé absente, révoquée ou d'un autre projet
      curl -sf "$API_URL" \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query":"{ products(page: 1, pageSize: 1) { items { id } total } }"}'

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

Trois limites s'appliquent à l'API mock runtime :

Périmètre	Limite	Une fois atteinte
Par adresse IP	60 requêtes par minute	429 TOO_MANY_REQUESTS — réessaie une minute plus tard
Par compte	Le quota de requêtes de ton forfait (par jour ou par mois)	429 TOO_MANY_REQUESTS jusqu'à la réinitialisation du quota
Par clé API	Acteurs simultanés — seulement si tu envoies des tokens d'acteur	429 MAX_ACTIVE_ACTORS_REACHED avec un en-tête Retry-After

Les projets invités sont décomptés du quota quotidien de la session invitée.

Gestion des erreurs

Une requête refusée répond avec un statut HTTP d'erreur et un corps JSON. Décide selon son code :

Statut HTTP	Code	Signification	Action
400	Bad Request	GraphQL invalide, opération inconnue ou désactivée, corps mal formé	Lire message ; corriger la requête ou le nom de l'opération
401	UNAUTHENTICATED	Aucune clé API envoyée (projet invité : token de partage absent ou erroné)	Envoyer Authorization: Bearer mck_…
401	API_KEY_INVALID	Clé inconnue, révoquée ou supprimée	Créer une nouvelle clé
401	API_KEY_EXPIRED	La date d'expiration de la clé est dépassée	Créer une nouvelle clé
401	ACTOR_TOKEN_INVALID	X-Actor-Token mal formé	Demander un token via /runtime/actors ou omettre l'en-tête
403	API_KEY_SCOPE_INSUFFICIENT	Clé de gestion uniquement	Utiliser une clé Runtime ou Full
404	PROJECT_NOT_FOUND	Slug inconnu, ou projet auquel la clé n'appartient pas (sur /runtime/actors : le projet de la clé a été supprimé)	Vérifier le slug ; utiliser une clé de ce projet
429	TOO_MANY_REQUESTS	Limite par IP ou quota du forfait atteint	Attendre, puis réessayer
429	MAX_ACTIVE_ACTORS_REACHED	Tous les emplacements d'acteur de la clé sont occupés	Attendre la durée Retry-After
429	RATE_LIMIT_EXCEEDED	Trop de demandes de token d'acteur pour une clé (POST /runtime/actors)	Attendre la durée Retry-After ; réutiliser un token tant qu'il est actif
503	QUERY_TIMEOUT	La requête a duré trop longtemps	Réessayer ; restreindre la requête

Format de réponse d'erreur

{
  "statusCode": 401,
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID",
  "path": "/mock/my-project/graphql",
  "timestamp": "2026-10-05T09:30:00.000Z"
}

Un 429 avec un en-tête Retry-After contient aussi retryAfter (en secondes) dans le corps. Une requête servie répond 200 avec un corps GraphQL ; les problèmes au niveau des données arrivent dans errors[] — par exemple, extensions.code NOT_READY signifie que la table n'est pas encore reliée à des données.

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.