DEV Community

Cover image for Comment simuler des API en ligne de commande
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment simuler des API en ligne de commande

Vous avez besoin d’une fausse API pendant le développement : le backend n’est pas prêt, un service tiers limite le débit, ou vos tests ne doivent pas appeler la production. Une API simulée (mock) permet de découpler le frontend, les tests et les dépendances externes. Ce guide montre comment la démarrer et l’automatiser depuis la ligne de commande.

Essayez Apidog dès aujourd’hui

Une API simulée définie uniquement dans une interface graphique est difficile à reproduire, versionner et exécuter en CI. À l’inverse, une simulation lancée par CLI devient une commande dans un script, une étape de pipeline et une opération qu’un agent de codage peut répéter.

Nous allons couvrir deux approches :

  1. Des outils open source qui démarrent un serveur mock local depuis un fichier.
  2. La CLI Apidog, qui importe une spécification et gère des simulations hébergées ainsi que des réponses personnalisées.

Pour comparer les options avant de choisir, consultez les meilleurs outils de simulation d’API et les outils de simulation d’API REST.

L’approche générale : exécuter un serveur d’API simulée depuis un fichier

Le modèle classique est simple : vous fournissez un fichier de spécification ou de données à un outil, qui expose ensuite un endpoint HTTP local. Aucun compte, aucune connexion et aucun projet distant ne sont nécessaires.

Choisissez l’outil selon votre point de départ :

Vous avez… Utilisez… Pour obtenir…
Une spécification OpenAPI Prism Une simulation conforme au contrat
Un environnement Mockoon ou une API avec des routes riches Mockoon CLI Un serveur headless pour la CI
Un fichier JSON de données json-server Une API REST avec état

Prism : servir une spécification OpenAPI

Si vous possédez déjà un fichier OpenAPI, Prism est une option directe. Il lit les paths, les exemples et les schémas, puis génère des réponses correspondant au contrat.

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Par défaut, Prism démarre sur http://127.0.0.1:4010. Vérifiez qu’il répond :

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

Prism renvoie :

  • l’example défini dans votre réponse OpenAPI ;
  • ou une valeur générée à partir du schéma si aucun exemple n’est fourni.

Il valide également les requêtes entrantes par rapport à la spécification. Une requête invalide reçoit donc une réponse 422 au lieu de passer silencieusement.

Pour l’installer globalement :

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

Vous pourrez ensuite remplacer npx @stoplight/prism-cli par prism.

Prism est sans état : un POST ne persiste pas de donnée. Utilisez-le lorsque votre priorité est la validation et le respect du contrat API.

Mockoon CLI : exécuter un environnement en mode headless

Mockoon CLI démarre une simulation depuis :

  • un fichier d’environnement exporté depuis l’application Mockoon ;
  • ou un fichier OpenAPI JSON/YAML. 
npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Par défaut, le serveur écoute sur le port 3000. Pour choisir un autre port :

npx @mockoon/cli start --data ./env.json --port 8080
Enter fullscreen mode Exit fullscreen mode

La CLI est utile si vous avez configuré visuellement des routes, règles et réponses dans Mockoon, mais que vous voulez les exécuter sans interface graphique dans un pipeline CI.

Installation globale :

npm install -g @mockoon/cli
Enter fullscreen mode Exit fullscreen mode

Vous obtenez alors la commande persistante :

mockoon-cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

C’est une bonne option pour des routes plus détaillées qu’une simple spécification OpenAPI. Un serveur de simulation léger pour une API RESTful répond souvent à ce besoin.

json-server : créer une API REST depuis JSON

Sans spécification OpenAPI, json-server est généralement le chemin le plus rapide. Créez un fichier db.json :

{
  "posts": [
    {
      "id": 1,
      "title": "Premier article",
      "published": true
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Démarrez ensuite le serveur :

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

Vous pouvez maintenant appeler :

curl http://localhost:3000/posts
Enter fullscreen mode Exit fullscreen mode

json-server expose automatiquement les opérations REST courantes :

GET    /posts
GET    /posts/:id
POST   /posts
PUT    /posts/:id
PATCH  /posts/:id
DELETE /posts/:id
Enter fullscreen mode Exit fullscreen mode

Contrairement à Prism, les écritures sont persistées dans le fichier JSON. Un POST ajoute un enregistrement, qui peut ensuite être récupéré avec un GET.

Installez-le globalement si nécessaire :

npm install -g json-server
Enter fullscreen mode Exit fullscreen mode

Vous bénéficiez aussi du filtrage, du tri et de la pagination par paramètres de requête.

Limites de l’approche par serveur local

Ces outils sont simples, autonomes et efficaces. En contrepartie, votre simulation, votre spécification, vos tests et votre documentation peuvent vivre dans des fichiers ou processus séparés.

Si vous avez besoin de correspondances de requêtes précises ou de relecture, MockServer et WireMock vont plus loin, avec un environnement Java.

L’approche Apidog CLI : importer la spécification et scripter les attentes

La CLI apidog ne démarre pas un serveur local depuis un fichier. Il n’existe pas de commande comme :

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Avec Apidog, la simulation est hébergée. La CLI sert à :

  1. importer votre spécification dans un projet ;
  2. générer des simulations pour les endpoints ;
  3. créer et gérer des réponses personnalisées, appelées attentes de simulation (mock expectations).

Apidog n’est pas open source : c’est un produit commercial disposant d’un niveau gratuit. Son intérêt est d’utiliser un projet commun pour la conception, la simulation et les tests, plutôt que de maintenir plusieurs fichiers et processus séparés.

Installez la CLI, puis authentifiez-vous :

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Le guide d’installation de l’Apidog CLI détaille la configuration du jeton d’accès.

Importer une spécification OpenAPI

Importez votre fichier OpenAPI dans un projet Apidog :

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Cette commande crée des simulations hébergées pour les opérations définies dans votre spécification.

Apidog utilise les types et les noms de champs du schéma pour générer des données cohérentes. Par exemple :

  • un champ email produit une adresse e-mail plausible ;
  • un champ createdAt produit un horodatage ;
  • les types définis dans le schéma sont respectés.

L’import accepte aussi les formats Swagger 2.0, Postman et Apidog. Une définition existante peut donc devenir une simulation accessible en une commande.

Créer des réponses personnalisées avec apidog mock

Les réponses générées automatiquement ne couvrent pas toujours vos scénarios de test. Vous pouvez définir une attente spécifique, par exemple :

  • retourner 200 pour un utilisateur existant ;
  • retourner 404 pour un identifiant précis ;
  • renvoyer un corps de réponse contrôlé pour un test d’erreur.

Commencez par lister les attentes existantes :

apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

La sortie est du JSON structuré. Vous pouvez l’utiliser avec jq pour extraire un identifiant avant une lecture, une modification ou une suppression.

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Les opérations create et update utilisent un fichier passé avec --file.

Valider une attente avant de l’envoyer

Ne construisez pas le JSON d’une attente à l’aveugle. La CLI fournit un schéma pour chaque commande d’écriture.

Récupérez le schéma :

apidog cli-schema get mock-create
Enter fullscreen mode Exit fullscreen mode

Créez votre fichier mock.json, puis validez-le :

apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Enfin, créez l’attente :

apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Pour une mise à jour, appliquez le même flux avec le schéma mock-update :

apidog cli-schema get mock-update
apidog cli-schema validate mock-update --file ./mock.json
apidog mock update --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Cette validation est particulièrement utile en CI : si le fichier est invalide, le pipeline échoue avant de modifier le projet.

Les commandes retournent du JSON contenant notamment agentHints.nextSteps, ce qui permet à un agent de codage ou à un script de déterminer l’étape suivante. Le guide complet de l’Apidog CLI couvre les autres groupes de commandes.

Intégrer la simulation dans une CI

Les deux approches sont compatibles CI : elles s’exécutent comme des commandes shell, retournent un code de sortie et produisent une sortie exploitable.

Exemple avec Prism

Démarrez Prism en arrière-plan, exécutez les tests, puis arrêtez le processus :

# Démarrer Prism en arrière-plan, puis lancer les tests
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

Dans un script plus robuste, utilisez un trap pour arrêter Prism même si les tests échouent :

npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

trap 'kill $PRISM_PID' EXIT

npm test
Enter fullscreen mode Exit fullscreen mode

Exemple avec Apidog

Avec Apidog, il n’y a aucun processus local à démarrer ou arrêter. Validez et appliquez l’attente avant de lancer les tests qui ciblent l’URL de simulation hébergée.

# Valider l'attente, puis l'appliquer au projet
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

L’intérêt est le même dans les deux cas : aucune action manuelle. Une équipe, un pipeline CI ou un agent IA peut recréer la même simulation à partir des mêmes commandes versionnées.

Difficultés courantes

S’attendre à ce que apidog mock démarre un serveur

apidog mock ne lance pas de processus local. Il n’existe pas de commande apidog mock start, apidog mock serve ou apidog mock ./file.yaml.

Utilisez plutôt :

  • apidog import pour créer des simulations hébergées depuis une spécification ;
  • apidog mock pour gérer les attentes personnalisées ;
  • Prism, Mockoon CLI ou json-server pour démarrer un serveur local depuis un fichier.

Ignorer la validation de schéma

Les commandes apidog mock create et apidog mock update lisent un fichier --file. Une structure invalide peut faire échouer la commande ou produire un résultat inattendu.

Avant chaque écriture, exécutez :

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Ces deux étapes évitent généralement une session de débogage inutile.

Obtenir des réponses peu utiles avec Prism

La qualité du mock Prism dépend de votre spécification. Si votre réponse ne contient ni example ni schéma précis, les données générées resteront vagues.

Ajoutez des exemples représentatifs dans OpenAPI :

responses:
  "200":
    description: Commande trouvée
    content:
      application/json:
        schema:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
        example:
          id: ord_123
          status: paid
Enter fullscreen mode Exit fullscreen mode

Attendre un comportement avec état d’un outil sans état

Prism et les simulations de contrat Apidog ne persistent pas les écritures. Si votre scénario exige qu’un POST soit suivi d’un GET retournant la nouvelle ressource, utilisez :

  • json-server pour une persistance dans un fichier JSON ;
  • ou une attente Apidog renvoyant explicitement la réponse attendue.

En résumé

La simulation par CLI transforme une tâche manuelle en commandes révisables, scriptables et exécutables en CI.

  • Utilisez Prism si vous avez une spécification OpenAPI et voulez valider le contrat.
  • Utilisez Mockoon CLI si vous avez besoin d’un environnement Mockoon complet en mode headless.
  • Utilisez json-server si vous voulez une API REST avec état à partir d’un fichier JSON.
  • Utilisez Apidog si vous voulez centraliser conception, simulation et tests dans un même projet, avec des simulations hébergées et des attentes versionnables via CLI.

Si vous voulez un serveur jetable depuis un fichier, les outils open source sont adaptés. Si vous voulez maintenir vos simulations synchronisées avec la conception et les tests, téléchargez Apidog, installez la CLI et automatisez vos simulations sans interface graphique.

Top comments (0)