API Contracts : Vos Spécifications d'API, Liées à votre Architecture
Il y a quelques semaines, je passais en revue une architecture système avec une équipe qui avait un superbe diagramme C4. Les conteneurs étaient bien définis. Les relations portaient des libellés clairs. Tout avait l'air parfait — jusqu'à ce que quelqu'un demande "à quoi ressemble concrètement l'API entre le Order Service et la Payment Gateway ?"
Silence. Le diagramme indiquait "REST/JSON." La spécification OpenAPI vivait dans un autre dépôt. La liste réelle des endpoints se trouvait dans une page Notion qui n'avait pas été mise à jour depuis le départ du dernier stagiaire. Trois sources de vérité pour une seule surface d'API, et aucune ne concordait.
C'est d'une banalité absurde. Les spécifications d'API sont parmi les artefacts les plus précis et les plus lisibles par des machines dans une codebase. Pourtant, dans la documentation d'architecture, elles sont invisibles. On obtient une boîte, une flèche et un libellé de protocole. Le contrat réel — les endpoints, les schémas, les champs — vit ailleurs, quelque part.
Nous avons créé les API Contracts pour résoudre ce problème. Vos spécifications d'API vivent désormais à l'intérieur de votre architecture, liées aux éléments qui les implémentent et les consomment.
Quatre Protocoles, un Seul Endroit
Les systèmes modernes parlent rarement un seul protocole. Votre API publique est en REST, vos services internes communiquent en gRPC, et votre frontend récupère ses données via GraphQL. Chacun a son propre format de spécification, son propre outillage, son propre écosystème de documentation.
Les API Contracts d'Archyl prennent en charge les quatre :
OpenAPI / Swagger — Importez vos spécifications OpenAPI 3.x ou Swagger 2.0 et obtenez un explorateur de référence interactif propulsé par Scalar. Les endpoints sont regroupés, les paramètres sont documentés, les schémas sont dépliables. C'est la même expérience qu'un outil de documentation d'API dédié, intégrée directement dans votre espace de travail d'architecture.
gRPC / Protocol Buffers — Collez ou synchronisez vos définitions .proto. Le visualiseur affiche les services, les méthodes, les types de messages et les enums avec coloration syntaxique et indentation appropriée. Plus besoin de fouiller dans les fichiers proto pour comprendre ce qu'un service expose.
GraphQL — Importez votre schéma et explorez les types, les queries, les mutations et les subscriptions. Et si vous avez configuré des endpoints serveur, vous disposez d'un playground GraphiQL complet — écrivez des requêtes, exécutez-les contre votre API réelle et explorez le schéma de manière interactive, le tout sans quitter Archyl.
AsyncAPI — Définissez vos APIs événementielles avec les spécifications AsyncAPI. Le visualiseur affiche les canaux, les opérations, les schémas de messages et les bindings serveur avec coloration syntaxique complète. Que vous utilisiez Kafka, RabbitMQ, NATS ou WebSockets, les contrats AsyncAPI documentent quels événements vos services produisent et consomment.
Importer depuis Git ou Coller Directement
Les spécifications d'API évoluent. Un endpoint est ajouté, un champ est déprécié, une nouvelle version est livrée. Si votre documentation nécessite un copier-coller manuel pour rester à jour, elle ne restera pas à jour.
C'est pourquoi les API Contracts proposent deux modes de source :
Git Sync connecte votre contrat à un fichier de spécification dans un dépôt. Pointez-le vers votre openapi.yaml, votre service.proto, votre schema.graphql ou votre asyncapi.yaml, et Archyl récupère le contenu directement. Quand la spécification change en amont, lancez une synchronisation et le contrat se met à jour. Cela fonctionne avec tous les fournisseurs Git supportés par Archyl — GitHub, GitLab, Bitbucket, Azure DevOps et les instances auto-hébergées.
Manuel est fait pour les équipes qui ne stockent pas leurs spécifications dans Git, ou pour du prototypage rapide. Collez le contenu de votre spécification directement et modifiez-le sur place. Utile pour ébaucher un contrat avant que le service n'existe, ou pour importer une spécification d'une API tierce que vous ne contrôlez pas.
Les deux modes supportent le versionnement, ce qui vous permet de suivre quelle version du contrat vous documentez.
Lié à votre Architecture
C'est ici que les API Contracts deviennent bien plus qu'un simple visualiseur de spécifications.
Chaque contrat peut être lié à un ou plusieurs éléments C4 — systèmes, conteneurs, composants ou éléments de code. Une spécification OpenAPI peut être liée au conteneur API Gateway qui la sert. Un proto gRPC peut être lié au composant microservice qui l'implémente. Un schéma GraphQL peut être lié au BFF (Backend for Frontend) qui l'expose.
Ces liens sont bidirectionnels. Depuis le contrat, vous voyez quels éléments d'architecture lui sont associés. Depuis le panneau de détail d'un élément sur le diagramme, vous voyez quels contrats décrivent sa surface d'API. Quand vous faites un clic droit sur un conteneur dans le canevas, vous pouvez lier et délier des contrats directement depuis le menu contextuel.
Cela comble le fossé que j'ai décrit au début. Quand quelqu'un demande "à quoi ressemble l'API entre ces deux services ?", la réponse est à un clic. Pas dans un autre outil, pas dans un autre dépôt — juste là, sur le diagramme.
Canaux d'Événements
Les architectures événementielles sont notoirement difficiles à documenter. Quel service publie sur quel topic ? Quel est le schéma du message ? Qui le consomme ?
Les Canaux d'Événements d'Archyl apportent de la visibilité à votre communication asynchrone. Chaque contrat AsyncAPI fait automatiquement apparaître les canaux qu'il définit — topics, queues, streams — et les associe aux éléments C4 qui produisent et consomment les événements.
Sur le diagramme, les canaux d'événements apparaissent comme des types de connexion distincts, rendant immédiatement visible quelles relations sont des appels API synchrones et lesquelles sont des flux d'événements asynchrones. C'est essentiel pour comprendre le comportement du système : un appel REST entre deux services a des caractéristiques de fiabilité et de couplage très différentes d'un événement publié vers un message broker.
Vous pouvez également créer des canaux d'événements indépendamment des contrats AsyncAPI, utile pour documenter des systèmes de messagerie legacy ou des protocoles propriétaires sans spécification formelle.
Visualiseurs Interactifs
Nous ne voulions pas que les contrats soient de simples blocs de texte brut. Chaque protocole dispose d'un visualiseur dédié :
Le visualiseur OpenAPI génère une référence d'API entièrement interactive. Les endpoints sont organisés par tag, avec des schémas de requête/réponse dépliables, une documentation des paramètres et les détails d'authentification. Si vous avez défini des URLs de serveur, le visualiseur les affiche pour que les développeurs sachent où envoyer leurs requêtes. C'est une vraie expérience de documentation d'API, pas un dump YAML avec coloration syntaxique.
Le visualiseur Protocol Buffer affiche les définitions proto avec une coloration syntaxique appropriée, rendant les services, RPCs et structures de messages faciles à parcourir.
Le visualiseur GraphQL met en évidence les types, les champs et les directives. Et quand vous avez configuré un endpoint serveur, un second onglet ouvre un playground GraphiQL complet. Vous pouvez écrire et exécuter des requêtes contre votre API en production, explorer le schéma par introspection et tester des mutations — le tout intégré dans Archyl. Si votre API GraphQL dispose de plusieurs environnements (staging, production), vous pouvez définir plusieurs entrées serveur et basculer entre elles.
Le visualiseur AsyncAPI affiche vos définitions d'API événementielles avec la liste des canaux, les schémas de messages et les configurations serveur/broker. Chaque canal montre ses opérations (publish/subscribe), les schémas de payload et les bindings — offrant aux développeurs une vision claire de votre surface de communication événementielle.
Comment Démarrer
Accédez à n'importe quel projet et ouvrez la section API Contracts depuis la barre latérale. Cliquez sur "Add Contract" et choisissez votre type de protocole et votre mode de source.
Pour les contrats sourcés depuis Git, connectez un dépôt (ou réutilisez-en un déjà connecté à votre projet), spécifiez le chemin du fichier et la branche, et Archyl récupère la spécification. Pour les contrats manuels, collez le contenu directement.
Une fois créé, rendez-vous sur le diagramme et liez le contrat aux éléments C4 concernés. À partir de ce moment, quiconque explore l'architecture peut accéder à la surface d'API réelle directement depuis le diagramme.
Pourquoi c'est Important
Les diagrammes d'architecture sont puissants pour montrer la structure — ce qui existe et comment les choses se connectent. Mais ils ont toujours été faibles sur les interfaces. Une flèche de relation libellée "REST/HTTPS" ne dit presque rien sur ce qui circule réellement entre deux services. Un événement publié sur un topic Kafka est encore plus opaque — à moins d'avoir la spécification AsyncAPI et le mapping des canaux juste là.
Les API Contracts comblent ce vide. Ils ajoutent de la précision aux flèches. Quand un nouveau membre de l'équipe regarde votre architecture et voit une connexion entre la Mobile App et l'API Gateway, il peut immédiatement ouvrir la spécification OpenAPI et comprendre exactement quels endpoints sont disponibles, quelles structures de données sont échangées et quelle authentification est requise.
C'est de la documentation d'architecture qui justifie son existence. Non pas parce que quelqu'un l'a imposée, mais parce qu'elle répond à de vraies questions qui se posent chaque jour.
Vous utilisez déjà Archyl pour votre architecture ? Explorez la fonctionnalité API Contracts dans votre projet. Nouveau sur la plateforme ? Découvrez le modèle C4 et comment la découverte propulsée par l'IA peut générer automatiquement votre diagramme d'architecture.