Aller au contenu
~/ blog / / approche-design-first-api

Maîtriser la Conception d'API : L'Approche Design-First

Définissez votre API avant de la coder. Une méthodologie qui évite le 'mais la spec a changé'.

· 5 min read ·
API Conception d'API OpenAPI Développement Bonnes Pratiques

J’ai vu des équipes passer des semaines à coder une API, puis découvrir à l’intégration que le frontend attendait un format complètement différent. Réunion de crise. Refactoring en urgence. Deadline repoussée.

Le problème n’était pas technique. C’était un problème de séquence. Ils avaient codé avant de se mettre d’accord.

L’approche API Design-First, c’est simple : on écrit le contrat avant le code. Tout le monde valide l’interface, puis chacun part bosser de son côté. Voici comment je l’applique.

Pourquoi designer avant de coder ?

Parce que changer un fichier YAML coûte zéro. Changer une route en production coûte cher.

Quand la spec existe avant le code :

  • Le frontend et le backend avancent en parallèle dès le jour 1.
  • Les discussions sur le format des données se font sur un document, pas dans un PR review.
  • Les nouvelles recrues lisent la spec et comprennent l’API sans lire l’implémentation.

Pas de magie là-dedans. Juste du bon sens appliqué tôt.

Étape 1 : Écrire le contrat

Le contrat, c’est un fichier OpenAPI (Swagger), RAML ou API Blueprint. Il décrit tout : endpoints, méthodes, schémas, authentification, codes d’erreur.

C’est ce fichier qui fait autorité. Pas le code. Pas le wiki Notion. Ce fichier.

openapi: 3.0.3
info:
  title: "API de Gestion des Utilisateurs"
  version: "1.0.0"
paths:
  /users/{id}:
    get:
      summary: Détails d'un utilisateur
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Utilisateur trouvé
        "404":
          description: Utilisateur introuvable

Étape 2 : Faire valider par tout le monde

J’insiste sur “tout le monde”. Pas juste les devs backend. Le frontend a des contraintes. Le QA a des questions. Le product owner a des cas d’usage que personne n’avait anticipés.

On partage la spec. On collecte les retours. On itère. Avant d’écrire la moindre ligne de logique métier.

La spec, c’est la source de vérité. Pendant tout le cycle de vie de l’API. Si le code diverge de la spec, c’est le code qui a tort.

Étape 3 : Monter des mocks

La spec est validée ? On génère des endpoints avec des réponses fictives. Le frontend peut intégrer immédiatement. Le backend implémente la vraie logique sans bloquer personne.

DEFINE route GET /users/{id}:
    RETURN mock_response({
        id: id,
        name: "Utilisateur Démo"
    })

J’ai bossé sur des projets où cette seule étape a fait gagner deux semaines au frontend. Deux semaines où ils n’attendaient plus personne.

Étape 4 : Implémenter la vraie logique

On remplace les mocks par le vrai code. La structure ne change pas — elle a été verrouillée à l’étape 2.

DEFINE route GET /users/{id}:
    user = base_donnees.recupererUtilisateur(id)
    IF user existe:
        RETURN données utilisateur (200)
    ELSE:
        RETURN erreur "Utilisateur introuvable" (404)

Si vous sentez le besoin de modifier le contrat à cette étape, c’est que la revue collaborative a été bâclée. Ça arrive. On revient à l’étape 2, on corrige, et on repart.

Étape 5 : Valider les entrées, formater les erreurs

Les données qui entrent dans votre API ne sont jamais propres. Validez tout. Et renvoyez des erreurs que le consommateur peut exploiter — pas un 500 générique.

DEFINE route POST /users:
    IF corps_requête respecte le schéma:
        CRÉER utilisateur
        RETURN données utilisateur (201)
    ELSE:
        RETURN erreurs de validation (400)

Un bon message d’erreur, c’est un message qu’un dev peut lire à 2h du matin sur un partage de connexion et comprendre ce qui ne va pas.

Étape 6 : Tester contre la spec

Les tests ne vérifient pas juste que “ça marche”. Ils vérifient que l’API respecte son contrat. Cas nominal, cas d’erreur, cas limites.

TEST récupération utilisateur valide:
    ENVOYER GET /users/{id_valide}
    ATTENDRE statut 200 + données correctes

TEST utilisateur inexistant:
    ENVOYER GET /users/{id_invalide}
    ATTENDRE statut 404 + message d'erreur

Ces tests tournent dans la CI. À chaque push. Si le contrat casse, le build casse. Pas de négociation.

Étape 7 : Générer la doc automatiquement

Swagger UI, Redoc ou équivalent. La doc se génère depuis la spec — la même spec que tout le monde a validée. Pas de doc écrite à la main qui finit par mentir.

Le vrai bénéfice

Ce n’est pas la qualité de l’API. C’est la qualité des conversations. Quand la spec existe en amont, les désaccords se règlent sur un fichier YAML, pas sur un bug en staging.

Concevez d’abord. Codez ensuite. Votre futur vous à 2h du matin vous remerciera.