DEV Community

Cover image for API Platform : Optimisez Votre Workflow API Design-First
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

API Platform : Optimisez Votre Workflow API Design-First

En bref

L’approche design-first consiste à rédiger la spécification de votre API avant le code d’implémentation. Cette spécification devient la source de vérité pour les maquettes, la documentation, les tests et les stubs client. En pratique, le bon outillage doit vous permettre de concevoir, simuler, documenter et valider une API sans maintenir plusieurs artefacts séparés.

Essayez Apidog aujourd’hui

Apidog

Essayez Apidog gratuitement

Introduction

La plupart des développeurs commencent avec une approche code-first :

  1. écrire une route ;
  2. ajouter quelques annotations ;
  3. générer une documentation ;
  4. espérer que la documentation reste alignée avec le comportement réel.

Cela fonctionne sur de petits projets. Mais dès que plusieurs développeurs interviennent, la documentation dérive rapidement.

Exemple classique :

// Documentation
["foo", "bar"]
Enter fullscreen mode Exit fullscreen mode

Mais l’API réelle renvoie :

[
  { "value": "foo" },
  { "value": "bar" }
]
Enter fullscreen mode Exit fullscreen mode

Le problème n’est pas seulement documentaire. Le frontend, les tests automatisés, les SDK et les intégrations externes peuvent tous dépendre d’un contrat qui n’est plus fiable.

Avec une approche design-first, le contrat API est défini avant l’implémentation. Le code, la documentation, les maquettes et les tests sont ensuite alignés sur cette spécification.

Ce que le "design-first" signifie en pratique

Le "design-first" n’est pas une technologie. C’est un workflow.

1. Définir le contrat avant le code

Avant d’écrire le contrôleur backend, vous définissez une spécification OpenAPI avec :

  • les chemins d’accès ;
  • les méthodes HTTP ;
  • les paramètres de chemin, requête et en-tête ;
  • les corps de requête ;
  • les schémas de réponse ;
  • les codes de statut ;
  • les règles d’authentification ;
  • les descriptions de champs ;
  • les exemples.

Exemple simplifié :

paths:
  /users/{id}:
    get:
      summary: Récupérer un utilisateur
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Utilisateur trouvé
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Utilisateur introuvable

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
        email:
          type: string
          format: email
Enter fullscreen mode Exit fullscreen mode

2. Générer une maquette utilisable

Une fois la spécification créée, le frontend peut consommer une API simulée sans attendre le backend.

Flux typique :

Spécification OpenAPI
        ↓
Serveur de maquette
        ↓
Développement frontend
Enter fullscreen mode Exit fullscreen mode

Cela permet au frontend et au backend de travailler en parallèle.

3. Implémenter contre la spécification

Le backend traite la spécification comme un document d’exigences.

Chaque endpoint implémenté doit respecter :

  • les paramètres attendus ;
  • les formats de requête ;
  • les codes de statut ;
  • les schémas de réponse ;
  • les erreurs prévues.

4. Valider automatiquement l’implémentation

Après l’implémentation, les tests doivent vérifier que l’API réelle correspond au contrat.

Exemple de vérification attendue :

GET /users/123
→ réponse HTTP 200
→ body conforme au schéma User
Enter fullscreen mode Exit fullscreen mode

Si la réponse ne respecte pas la spécification, le test échoue.

5. Mettre à jour la spécification avant tout changement

Quand une exigence change, le workflow doit rester le même :

  1. modifier la spécification ;
  2. faire relire le changement ;
  3. mettre à jour les maquettes ;
  4. adapter l’implémentation ;
  5. exécuter les tests de contrat.

Ce dont une plateforme "design-first" a besoin

Tous les outils API ne sont pas adaptés à un workflow "design-first". Voici les fonctionnalités importantes.

Éditeur d’API visuel

Écrire du YAML à la main peut être lent et source d’erreurs, surtout sur de grandes API.

Un bon éditeur visuel doit permettre de définir :

  • les endpoints ;
  • les méthodes HTTP ;
  • les paramètres ;
  • les bodies ;
  • les réponses ;
  • les schémas réutilisables ;
  • les exemples ;
  • les règles de validation.

Il doit aussi générer une spécification OpenAPI valide.

Validation OpenAPI en temps réel

La spécification doit être valide avant d’être utilisée pour générer une documentation, une maquette ou des tests.

Une validation utile doit signaler immédiatement :

  • les champs manquants ;
  • les références $ref invalides ;
  • les types incohérents ;
  • les réponses mal structurées ;
  • les erreurs de syntaxe.

Maquettes générées automatiquement

Le workflow idéal est simple :

Définir la spécification → obtenir une maquette utilisable
Enter fullscreen mode Exit fullscreen mode

Aucune conversion manuelle ne devrait être nécessaire.

La maquette doit respecter les types et contraintes définis dans le schéma :

email:
  type: string
  format: email

age:
  type: integer
  minimum: 18
  maximum: 99
Enter fullscreen mode Exit fullscreen mode

Une bonne maquette doit donc générer :

{
  "email": "user@example.com",
  "age": 42
}
Enter fullscreen mode Exit fullscreen mode

Documentation générée depuis la spécification

La documentation ne doit pas être maintenue séparément.

Elle doit être produite depuis la même source que :

  • les maquettes ;
  • les tests ;
  • les schémas ;
  • les exemples ;
  • les contrats API.

Cela limite les écarts entre ce qui est documenté et ce qui est réellement attendu.

Workflow de révision d’équipe

Une modification de contrat API doit être traitée comme une modification de code.

Le workflow devrait permettre :

  • les commentaires sur un endpoint ;
  • les commentaires sur un champ spécifique ;
  • l’historique des changements ;
  • la revue asynchrone ;
  • la validation avant implémentation.

Export OpenAPI standard

Votre spécification doit rester portable.

Vous devez pouvoir exporter l’API en OpenAPI standard pour l’utiliser avec :

  • des générateurs de code ;
  • des passerelles API ;
  • des outils de test ;
  • des validateurs de schéma ;
  • des outils CI/CD.

Apidog en tant que plateforme "design-first"

Apidog est organisé autour de la spécification API comme artefact principal. La conception, la documentation, les maquettes et les tests sont connectés à la même définition d’API.

Éditeur OpenAPI visuel

Dans Apidog, la conception d’un endpoint se fait via une interface structurée.

Pour chaque route, vous pouvez définir :

  • le chemin ;
  • la méthode HTTP ;
  • les paramètres ;
  • le corps de requête ;
  • les réponses ;
  • les schémas ;
  • les exemples ;
  • les règles de validation.

Vous pouvez travailler sans écrire directement du YAML. Si vous préférez éditer la spécification brute, Apidog propose aussi une vue YAML/JSON.

Les deux vues restent synchronisées.

Exemple de schéma réutilisable :

components:
  schemas:
    UserProfile:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
Enter fullscreen mode Exit fullscreen mode

Vous pouvez ensuite le référencer dans plusieurs endpoints :

schema:
  $ref: "#/components/schemas/UserProfile"
Enter fullscreen mode Exit fullscreen mode

Cela évite de dupliquer les mêmes structures dans toute l’API.

Prévisualisation de la documentation en temps réel

Pendant la conception, la documentation générée peut être prévisualisée.

Cela permet de vérifier rapidement :

  • si les descriptions sont compréhensibles ;
  • si les réponses sont lisibles ;
  • si les exemples sont utiles ;
  • si les schémas sont cohérents ;
  • si un frontend peut intégrer l’endpoint sans poser de questions supplémentaires.

Ce point est important : si la documentation générée n’est pas claire, la spécification ne l’est probablement pas non plus.

Maquette intelligente depuis la spécification

Quand un endpoint est enregistré dans Apidog, le serveur de maquettes peut être utilisé immédiatement.

La maquette génère des réponses basées sur les schémas définis.

Exemples de comportement attendu :

  • un champ format: email renvoie une adresse e-mail valide ;
  • un entier avec minimum et maximum respecte la plage ;
  • une énumération renvoie une valeur autorisée ;
  • les objets imbriqués suivent le schéma ;
  • les références $ref sont résolues.

Exemple de schéma :

status:
  type: string
  enum:
    - active
    - inactive
    - pending
Enter fullscreen mode Exit fullscreen mode

Exemple de réponse simulée :

{
  "status": "active"
}
Enter fullscreen mode Exit fullscreen mode

Vous pouvez aussi définir des règles de maquette personnalisées, par exemple :

  • retourner 404 si id = 0 ;
  • retourner une réponse spécifique pour un paramètre donné ;
  • simuler un cas d’erreur ;
  • préparer des scénarios frontend avant que le backend soit prêt.

Révision d’équipe et suivi des changements

Dans Apidog, les changements de spécification sont visibles dans l’espace de travail.

Pour un workflow "design-first", cela permet de :

  • discuter d’un endpoint avant son implémentation ;
  • commenter une réponse ou un champ ;
  • suivre qui a modifié quoi ;
  • éviter les changements silencieux de contrat ;
  • aligner frontend et backend avant le développement.

Design-first vs. Code-first : les véritables compromis

Le "design-first" n’est pas toujours supérieur. Il dépend du contexte.

Avantages du "design-first"

  • Le frontend et le backend peuvent travailler en parallèle.
  • La documentation reste alignée avec le contrat.
  • Les problèmes d’intégration apparaissent plus tôt.
  • Les contrats API sont explicites.
  • Les changements sont revus avant implémentation.
  • Les tests peuvent valider automatiquement le respect du contrat.

Inconvénients du "design-first"

  • Il faut définir la spécification avant de coder.
  • L’équipe doit apprendre l’outil de spécification.
  • Le workflow demande de la discipline.
  • Une spécification trop détaillée trop tôt peut figer de mauvaises décisions.

Avantages du "code-first"

  • Démarrage rapide pour les prototypes.
  • Moins de processus pour un développeur solo.
  • Pas besoin d’outil de conception séparé.
  • Pratique pour explorer un domaine encore instable.

Inconvénients du "code-first"

  • La documentation devient souvent secondaire.
  • Le frontend doit attendre le backend.
  • Les changements de contrat sont moins visibles.
  • Les écarts entre code et documentation sont fréquents.
  • La refactorisation demande des mises à jour manuelles.

En général, dès qu’une API implique plusieurs développeurs ou plusieurs consommateurs, le "design-first" devient plus rentable.

Outils supportant les workflows "design-first"

Apidog

Apidog fournit une plateforme complète pour concevoir, simuler, documenter, tester et réviser des API dans un seul outil.

Points clés :

  • éditeur visuel ;
  • génération de maquettes ;
  • documentation ;
  • tests ;
  • collaboration d’équipe ;
  • export OpenAPI.

Stoplight Studio

Stoplight Studio est un éditeur OpenAPI solide, avec Spectral pour le linting et la gouvernance des spécifications.

Il convient bien aux organisations qui veulent standardiser leurs pratiques OpenAPI, mais il ne couvre pas tous les besoins de maquette et de test dans un seul workflow.

SwaggerHub

SwaggerHub est une plateforme mature pour l’édition et la collaboration OpenAPI.

Elle est largement utilisée en entreprise et s’intègre bien dans l’écosystème Swagger. Ses capacités de maquette et de test sont toutefois plus limitées que celles d’une plateforme complète orientée "design-first".

Postman avec API Builder

Postman propose des fonctionnalités de conception d’API et de génération de spécifications OpenAPI.

Cependant, les workflows de conception, collections et maquettes peuvent sembler séparés. Il reste particulièrement adapté aux équipes qui utilisent déjà Postman pour tester et documenter leurs APIs.

Insomnia avec mode document

Insomnia prend en charge l’édition de spécifications OpenAPI et fournit des fonctionnalités de maquette de base.

C’est une option légère pour des développeurs individuels ou des petites équipes, mais moins complète pour un workflow "design-first" collaboratif.

Mettre en place un workflow "design-first" dans Apidog

Étape 1 : créer le projet depuis la spécification

Commencez par créer un projet API dans Apidog, puis ouvrez l’espace de conception.

Évitez de commencer par envoyer des requêtes manuelles. Définissez d’abord le contrat :

  • endpoint ;
  • méthode HTTP ;
  • paramètres ;
  • schéma de réponse ;
  • codes d’erreur.

Étape 2 : définir les composants partagés

Avant d’ajouter tous les endpoints, créez les schémas réutilisables.

Exemples :

ErrorResponse:
  type: object
  required:
    - code
    - message
  properties:
    code:
      type: string
    message:
      type: string
Enter fullscreen mode Exit fullscreen mode 
Pagination:
  type: object
  properties:
    page:
      type: integer
    pageSize:
      type: integer
    total:
      type: integer
Enter fullscreen mode Exit fullscreen mode

Cela évite d’avoir plusieurs formats d’erreur ou de pagination dans la même API.

Étape 3 : créer un premier endpoint complet

Pour chaque endpoint, définissez au minimum :

  • la méthode ;
  • le chemin ;
  • les paramètres obligatoires ;
  • la réponse 200 ou 201 ;
  • les erreurs courantes (400, 401, 404, 422, 500) ;
  • un exemple de réponse.

Exemple de réponse d’erreur :

{
  "code": "USER_NOT_FOUND",
  "message": "Utilisateur introuvable"
}
Enter fullscreen mode Exit fullscreen mode

Étape 4 : partager l’URL de maquette

Dès que l’endpoint est défini, récupérez l’URL de maquette dans Apidog et partagez-la avec le frontend.

Le frontend peut alors intégrer l’API simulée :

const response = await fetch("https://mock.example.com/users/123");
const user = await response.json();

console.log(user.email);
Enter fullscreen mode Exit fullscreen mode

Le backend peut avancer en parallèle sans bloquer l’interface.

Étape 5 : relire la documentation générée

Avant d’écrire le code backend, ouvrez la documentation générée.

Vérifiez :

  • les noms de champs ;
  • les descriptions ;
  • les exemples ;
  • les erreurs ;
  • les contraintes ;
  • les cas limites.

Si la documentation générée n’est pas exploitable, corrigez la spécification.

Étape 6 : verrouiller le contrat pour le sprint

Une fois la revue terminée, considérez la spécification comme stable pour le sprint.

Si une modification devient nécessaire :

  1. mettez à jour la spécification ;
  2. prévenez les consommateurs de l’API ;
  3. ajustez la maquette ;
  4. modifiez le backend ;
  5. relancez les tests.

Étape 7 : valider les réponses avec des tests

Après l’implémentation, ajoutez des tests pour vérifier que les réponses respectent les schémas.

Le but est simple :

API réelle == spécification OpenAPI
Enter fullscreen mode Exit fullscreen mode

Dans une CI, ce type de validation sert de garde-fou contre les régressions de contrat.

FAQ

Le "design-first" est-il uniquement pour les API REST ?

Non. Le principe s’applique à tout système basé sur un contrat.

Exemples :

  • REST avec OpenAPI ;
  • GraphQL avec une approche schema-first ;
  • gRPC avec protobuf ;
  • systèmes événementiels avec AsyncAPI.

Apidog supporte la conception REST et GraphQL. Pour gRPC, les fichiers proto jouent un rôle similaire de contrat initial.

Faut-il définir toute l’API avant de commencer ?

Non.

Vous pouvez appliquer le "design-first" fonctionnalité par fonctionnalité.

Exemple :

Sprint actuel → définir uniquement les endpoints nécessaires à cette fonctionnalité
Enter fullscreen mode Exit fullscreen mode

L’adoption incrémentale est souvent plus réaliste que la migration complète d’un seul coup.

Comment intégrer le "design-first" dans un sprint agile ?

Une approche simple :

  1. concevoir le contrat en début de sprint ;
  2. faire relire par le frontend et le backend ;
  3. générer la maquette ;
  4. développer en parallèle ;
  5. valider l’implémentation contre la spécification.

La revue de spécification devient alors une partie de la planification technique.

Que faire si l’implémentation doit s’écarter de la spécification ?

Cela arrive.

Le bon ordre est :

  1. modifier la spécification ;
  2. faire valider le changement ;
  3. mettre à jour la maquette ;
  4. modifier l’implémentation ;
  5. adapter les tests.

L’objectif est de garder la spécification comme source de vérité.

Peut-on générer des stubs serveur depuis l’export OpenAPI d’Apidog ?

Oui. Exportez la spécification en OpenAPI 3.x, puis utilisez un générateur standard comme openapi-generator.

Exemple :

openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./server-stub
Enter fullscreen mode Exit fullscreen mode

openapi-generator prend en charge de nombreux langages et frameworks.

Comment gérer le versionnement des spécifications ?

Apidog conserve l’historique des changements dans un projet.

Pour des versions majeures maintenues en parallèle, par exemple v1 et v2, vous pouvez utiliser des projets ou branches séparés selon l’organisation de votre équipe.

Conclusion

Le "design-first" réduit les surprises d’intégration en rendant le contrat API explicite dès le début.

Le workflow recommandé est simple :

  1. définir la spécification ;
  2. générer la maquette ;
  3. partager la documentation ;
  4. implémenter contre le contrat ;
  5. valider automatiquement les réponses.

L’investissement initial est faible si l’outil rend la conception rapide. C’est précisément le rôle d’une plateforme comme Apidog : centraliser la spécification, les maquettes, la documentation, les tests et la collaboration pour rendre le "design-first" pratique au quotidien.

Top comments (0)