Comment concevoir et développer des API selon l'approche Git-native

La plupart des équipes API considèrent le contrat comme une réflexion après coup. Elles écrivent d'abord le code, génèrent ensuite une spécification, puis les regardent diverger. La conception API "git-native" inverse cet ordre. Vous traitez le contrat API comme du code source, le versionnez dans Git et révisez chaque changement de la même manière que vous révisez la logique applicative.

Ce guide porte sur la discipline, pas sur un seul outil. Vous apprendrez à concevoir des contrats dans des branches, à les réviser dans des pull requests et à transformer une spécification validée en mocks, tests et documentation. L'objectif est un flux de travail où votre historique Git est votre historique API.

Si vous savez déjà à quoi ressemble l'outillage "Spec-First" et que vous souhaitez la présentation du produit, lisez l'article complémentaire sur le flux de travail API "git-native". Cet article reste centré sur la pratique.

Ce que signifie "git-native" pour le travail API

"Git-native" signifie que votre définition API réside dans votre dépôt en tant que fichier texte brut. Pas dans une base de données cloud propriétaire. Pas derrière un login de fournisseur. Un fichier .yaml ou .json situé à côté de votre code, suivi par le même système de contrôle de version que votre équipe utilise déjà.

Comparez cela aux outils "cloud-locked". De nombreuses plateformes de conception d'API stockent le contrat dans leur propre backend. Vous éditez via une interface utilisateur web, et la version canonique réside sur leurs serveurs. Votre dépôt contient au mieux une exportation obsolète. Lorsque la base de données du fournisseur est la source de vérité, votre historique Git ne vous dit rien sur l'évolution de l'API.

Le modèle "git-native" inverse cette relation. Le fichier dans main est le contrat. Tout le reste, y compris toute interface graphique, est une vue sur ce fichier. Ce simple changement débloque l'historique, la responsabilité, le retour arrière et la révision pour votre surface API.

Une configuration "git-native" possède trois propriétés. La spécification est un fichier texte dans le dépôt. Les changements passent par des opérations Git normales comme le branchement, le commit et le merge. Et chaque artefact en aval, des mocks à la documentation, dérive du fichier validé plutôt que d'une base de données distincte.

Pourquoi concevoir et développer des API dans Git

Vous faites déjà confiance à Git pour votre actif le plus précieux : votre code. Votre contrat API mérite le même traitement.

L'historique est la première raison. Quand quelqu'un demande "quand avons-nous ajouté le paramètre de pagination cursor ?", git log répond en quelques secondes. Le commit qui l'a introduit contient un message, un auteur et une date. Pas de captures d'écran, pas d'archéologie de changelog.

La responsabilité est la deuxième. Exécutez git blame sur le fichier de spécification et vous verrez exactement qui a modifié chaque ligne et pourquoi. Un nom de champ confus remonte à la PR qui l'a ajouté, avec la discussion associée. La responsabilisation devient automatique.

Le retour arrière est la troisième. Une mauvaise conception est livrée. Avec Git, vous git revert le merge et le contrat revient à son état antérieur. La génération de code en aval, les mocks et la documentation se régénèrent à partir du fichier annulé. Il n'y a pas de nettoyage manuel dans un système séparé.

La révision est la quatrième, et c'est celle que les équipes sous-utilisent. Une pull request est l'endroit naturel pour débattre d'une conception API avant qu'elle ne devienne réelle. Les relecteurs commentent une ligne + qui ajoute un champ requis. La conversation reste attachée au changement pour toujours.

La source unique de vérité lie tout cela. Lorsque le contrat est un seul fichier dans main, il n'y a aucune ambiguïté quant à la version réelle. Le frontend, le backend, l'AQ et la documentation lisent tous la même ligne de YAML. C'est la promesse fondamentale d'un flux de travail de spécification API basé sur Git.

La boucle de conception API "git-native"

La boucle comporte cinq étapes : concevoir le contrat, commiter, ouvrir une PR, réviser et fusionner. L'implémentation suit le merge, et non l'inverse.

Commencez par écrire le contrat. Supposons que vous ajoutiez un endpoint pour récupérer les factures d'un utilisateur. Vous créez une branche et modifiez le fichier OpenAPI.

# openapi.yaml (excerpt added on branch feat/invoices-list)
paths:
 /users/{userId}/invoices:
 get:
 operationId: listUserInvoices
 summary: List invoices for a user
 parameters:
 - name: userId
 in: path
 required: true
 schema: { type: string, format: uuid }
 - name: status
 in: query
 required: false
 schema:
 type: string
 enum: [draft, open, paid, void]
 responses:
 "200":
 description: A page of invoices
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/InvoiceList"
 "404":
 description: User not found

Validez ce changement avec un message clair : git commit -m "Add GET /users/{userId}/invoices contract". Le commit est petit et ciblé. Il décrit une décision de conception.

Maintenant, ouvrez une pull request. Le diff montre aux relecteurs exactement ce qui est nouveau : un chemin, une opération, deux paramètres, deux réponses. Vos coéquipiers discutent des noms, des valeurs d'énumération et si le code 404 est le bon pour un utilisateur manquant. Ils pourraient insister pour la pagination par curseur avant qu'une seule ligne de code de gestionnaire n'existe.

Une fois la PR approuvée, fusionnez-la. Le contrat dans main inclut désormais le point de terminaison des factures. L'implémentation vient ensuite, et elle est contrainte par la spécification sur laquelle vous avez tous convenu. Cet ordre est ce que les gens entendent par développement API "spec-first" : l'accord précède le code.

L'avantage est que les débats de conception coûtent peu cher. Changer un champ YAML en révision coûte des minutes. Changer un point de terminaison livré, implémenté et documenté coûte des jours.

Stratégie de branchement pour les contrats API

Traitez les modifications de contrat comme tout autre changement : une branche par unité de travail logique. Une branche par endpoint ou par modification maintient les PR petites et les diffs lisibles.

Nommez les branches de manière à ce que l'intention soit évidente. Utilisez un préfixe qui signale la classe de changement. Cela aide les réviseurs et l'intégration continue à acheminer le travail.

Le préfixe a une signification. Une branche break/api- indique aux réviseurs de ralentir et de vérifier chaque consommateur. Une branche chore/api- signale l'absence de changement sémantique, de sorte que la révision peut être rapide.

Vous choisissez également un modèle de branchement. Le développement basé sur le tronc convient à la plupart des équipes API. Des branches de courte durée fusionnent quotidiennement dans main, et la spécification reste proche d'une seule ligne de vérité. Gitflow, avec des branches develop et release de longue durée, convient aux équipes qui regroupent les modifications d'API en versions planifiées.

Pour la plupart des travaux API, préférez le développement basé sur le tronc. Des modifications de contrat petites et fréquentes produisent des diffs petits et fréquents. Les branches de longue durée laissent la spécification dériver, et les conflits de fusion YAML deviennent rapidement désagréables lorsque deux branches restructurent le même fichier.

Révision de la conception API dans les pull requests

Une PR de spécification est une révision de conception, pas une vérification syntaxique. Les relecteurs examinent la sémantique, et quelques questions couvrent la majeure partie du risque.

Cela rompt-il les consommateurs existants ? Supprimer un champ, renommer un chemin ou resserrer un type sont tous des changements cassants. Un relecteur vérifie si le changement est additif ou cassant, et les changements cassants exigent une augmentation de version ou un chemin de dépréciation.

Le nommage est-il cohérent ? Si chaque endpoint de collection utilise des noms pluriels, un nouveau chemin singulier se démarque. Si les erreurs renvoient un champ code ailleurs, un nouveau endpoint devrait également le faire. Les relecteurs appliquent les modèles déjà établis par l'API.

Est-ce "diff-friendly" ? Gardez le YAML stable afin que les diffs restent petits. Ordonnez les clés de manière cohérente. Ajoutez de nouveaux chemins à un endroit prévisible. Un relecteur peut lire un diff de cinq lignes en quelques secondes, mais un fichier réordonné produit un diff de cent lignes qui masque le véritable changement.

Changement cassant "reviewer-friendly". Les lignes - indiquent exactement ce qui disparaît.

# Diff qu'un relecteur voit dans la PR
 parameters:
 - name: status
 in: query
 schema:
 type: string
- enum: [draft, open, paid, void]
+ enum: [draft, open, paid, void, uncollectible]

Ce diff est additif à l'énumération, il est donc sûr. Comparez-le à une ligne - qui supprime entièrement void, ce qui casserait tout client envoyant cette valeur. Le diff rend la différence visible en un coup d'œil.

Encouragez les relecteurs à commenter en ligne sur la spécification, de la même manière qu'ils commentent le code. La discussion reste attachée à la ligne et survit dans l'historique fusionné.

De la conception au développement

Une fois le contrat dans main, il devient la source de tout ce qui se trouve en aval. Vous générez, vous n'écrivez pas à la main.

La génération de code vient en premier. Des outils comme openapi-generator produisent des stubs de serveur et des clients typés à partir du fichier validé. Vos gestionnaires remplissent la logique métier, mais les formes de requête et de réponse correspondent au contrat par construction. La spécification et le code ne peuvent pas être en désaccord sur le format filaire.

Les mocks viennent ensuite. Un serveur de mock lit la spécification et renvoie des exemples de réponses pour chaque endpoint. Les développeurs front-end développent contre le mock avant même que le backend n'existe. Ils commencent dès que le contrat fusionne, et non des semaines plus tard.

Les tests suivent. Les tests de contrat affirment que votre serveur en cours d'exécution correspond à la spécification. Envoyez une requête, validez la réponse par rapport au schéma et faites échouer la build si elles divergent. C'est la garde-fou contre la dérive spécification/code.

La documentation est également générée. La documentation de référence est rendue directement à partir du fichier OpenAPI. Lorsque le contrat change, la documentation change dans le même commit. Il n'y a pas de mise à jour de documentation séparée à oublier.

Le principe est cohérent. Chaque artefact dérive d'un seul fichier validé. Régénérez à chaque fusion, et vos mocks, clients, tests et documentation restent synchronisés avec le contrat.

Conventions d'équipe qui évoluent

Les conventions sont ce qui empêche un flux de travail "git-native" de s'effondrer à mesure que l'équipe grandit. Décidez-les tôt et mettez-les par écrit.

Premièrement, choisissez entre un seul fichier de spécification et plusieurs. Un seul openapi.yaml est simple mais devient ingérable au-delà de quelques dizaines d'endpoints. Diviser en plusieurs fichiers avec des références $ref maintient chaque fichier lisible, au prix d'une étape de regroupement. Un modèle courant est un fichier par ressource, regroupé en une seule spécification au moment de la compilation.

Deuxièmement, versionnez délibérément. Augmentez la version info.version d'OpenAPI à chaque changement significatif, et suivez le versionnement sémantique. Les changements additifs augmentent la version mineure. Les changements cassants augmentent la version majeure et signifient généralement un nouveau préfixe de chemin comme /v2/.

Troisièmement, tenez un journal des modifications. Un CHANGELOG.md à côté de la spécification enregistre ce qui a changé et pourquoi en termes humains. L'historique Git est précis mais verbeux ; le changelog est le résumé lisible que vos consommateurs parcourent réellement.

Quatrièmement, protégez la spécification avec CODEOWNERS. Exigez que les responsables d'API approuvent tout changement au fichier de contrat. Cela empêche les contributeurs bien intentionnés de livrer des conceptions incohérentes.

# .github/CODEOWNERS
/api/openapi.yaml @api-stewards
/api/paths/ @api-stewards

Cinquièmement, utilisez un linter en CI. Un linter détecte les problèmes de style et de cohérence avant la révision. Exécutez-le sur chaque PR afin que les humains révisent la conception, pas le formatage.

# .github/workflows/api-lint.yml
name: API Lint
on:
 pull_request:
 paths: ["api/"]
jobs:
 spectral:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Run Spectral
 run: npx @stoplight/spectral-cli lint api/openapi.yaml --fail-severity warn

Avec le linting en CI et les CODEOWNERS, chaque modification de contrat est soumise à des vérifications automatisées et à un responsable humain. Cette combinaison s'adapte de trois ingénieurs à trois cents.

Pièges courants et comment les éviter

La conception API "git-native" présente des modes de défaillance prévisibles. Les connaître vous permet de les contourner.

La dérive spécification/code est la pire. Le contrat dit une chose ; le serveur en cours d'exécution en fait une autre. Prévenez-la avec des tests de contrat en CI qui valident les réponses en direct par rapport à la spécification validée. S'ils divergent, la build échoue. La dérive devient un pipeline cassé, pas une surprise en production.

Les PR géantes sont le piège suivant. Une seule branche qui ajoute vingt endpoints produit un diff irrévisable. Les relecteurs survolent, approuvent et manquent des problèmes. Divisez le travail en un endpoint ou un changement par PR. Les petits diffs obtiennent une vraie révision.

Les artefacts écrits à la main causent une incohérence silencieuse. Lorsque quelqu'un écrit un client à la main au lieu de le générer, le client s'éloigne de la spécification. Générez les clients, les stubs et la documentation à partir du fichier validé à chaque fois. Traitez les artefacts API écrits à la main comme un signal d'alarme.

Les conflits de fusion YAML frustrent les équipes sur les branches de longue durée. Deux branches restructurent le même fichier et Git ne peut pas les réconcilier. Évitez cela avec des branches de courte durée, un ordre de clés stable et une disposition de fichiers séparés afin que les changements touchent des fichiers différents. Le développement basé sur le tronc, combiné à de petites PR, élimine la plupart des conflits avant qu'ils ne commencent.

Le modèle commun aux quatre est le même. Maintenez les changements petits, dérivez les artefacts de la spécification et laissez la CI faire respecter le contrat. La discipline l'emporte sur l'héroïsme.

Où Apidog s'intègre

Vous pouvez exécuter un flux de travail "git-native" avec un éditeur de texte et une CLI. De nombreuses équipes souhaitent une interface graphique pour la conception sans abandonner Git comme source de vérité. C'est l'écart que le Mode Spec-First d'Apidog comble.

Le Mode Spec-First conserve le fichier OpenAPI dans votre dépôt Git et dispose d'une synchronisation bidirectionnelle. Vous modifiez le contrat dans le concepteur visuel d'Apidog ou dans votre éditeur, et les deux restent cohérents avec le fichier de votre dépôt. Le fichier dans Git reste canonique, de sorte que les branches, les PR et l'historique fonctionnent exactement comme décrit ici. Vous obtenez l'interface graphique sans le verrouillage du cloud. Consultez la documentation du Mode Spec-First pour les détails de configuration.

L'important n'est pas l'outil. C'est que vous pouvez avoir une surface de conception visuelle et une discipline "git-native" en même temps. Le dépôt reste la source unique de vérité, et Apidog en devient une vue.

FAQ

La conception API "git-native" est-elle uniquement pour OpenAPI ?

Non. La discipline s'applique à tout format de contrat basé sur du texte. OpenAPI est le plus courant, mais le même flux de travail fonctionne pour AsyncAPI, les fichiers .proto gRPC ou le SDL GraphQL. Tant que le contrat est un fichier texte que vous pouvez différencier, brancher et réviser, il est "git-native".

Comment gérer les changements cassants dans un flux de travail "git-native" ?

Rendez les changements cassants visibles et délibérés. Utilisez un préfixe de branche break/api-, augmentez la version majeure et exigez l'approbation du responsable via CODEOWNERS. Dans la mesure du possible, ajoutez la nouvelle forme à côté de l'ancienne et dépréciez l'ancien chemin selon un calendrier. Le diff de la PR et l'augmentation de version signalent ensemble la rupture à chaque consommateur.

La spécification API doit-elle résider dans le même dépôt que le code ?

Généralement oui, lorsqu'une seule équipe possède les deux. Co-localiser la spécification et l'implémentation signifie qu'une seule PR peut modifier le contrat et le gestionnaire ensemble, et les tests de contrat s'exécutent dans un seul pipeline. Placez la spécification dans un dépôt séparé uniquement lorsque de nombreuses équipes consomment une API partagée et ont besoin d'un versionnement indépendant.

Comment empêcher la spécification et le code de diverger ?

Ajoutez des tests de contrat à la CI. Ils envoient de vraies requêtes à votre serveur en cours d'exécution et valident chaque réponse par rapport à la spécification validée. Une divergence fait échouer la build. Combinés à la génération de stubs et de clients à partir de la spécification, les tests de contrat transforment la dérive en échec de pipeline plutôt qu'en bug de production.

Conclusion

La conception API "git-native" est une discipline, pas un produit. Vous traitez le contrat comme du code source, le faites évoluer dans des branches, le révisez dans des pull requests et générez chaque artefact en aval à partir du fichier validé. L'historique, la responsabilité, le retour arrière et la révision sont gratuits car Git vous les offre déjà.

Commencez petit. Déplacez votre spécification dans le dépôt, ajoutez une étape de lint et exigez une révision sur les changements de contrat. Développez à partir de là avec la génération de code, les mocks et les tests de contrat. Le flux de travail s'accumule : chaque convention facilite la suivante, et votre historique Git devient un enregistrement complet de la croissance de votre API.

Si vous souhaitez une surface de conception visuelle qui conserve la spécification dans Git, essayez le Mode Spec-First dans Apidog et voyez comment la synchronisation bidirectionnelle s'adapte au flux de travail ci-dessus.