Contrats d'API - Archyl Docs

Documentez et gérez vos spécifications d'API directement liées aux éléments de votre architecture C4

Contrats d'API

Les Contrats d'API vous permettent d'attacher des spécifications d'API à vos éléments d'architecture, gardant documentation et conception synchronisées. Archyl supporte les contrats OpenAPI (REST), gRPC, GraphQL, AsyncAPI et MCP, avec synchronisation git optionnelle ou découverte live.

Types de Contrats Supportés

Type Format Cas d'usage
HTTP (REST) OpenAPI 3.x (YAML/JSON) APIs REST, webhooks
gRPC Protocol Buffers (.proto) RPC service-à-service
GraphQL GraphQL SDL (.graphql) APIs de requêtes
Async AsyncAPI (YAML/JSON) APIs événementielles, files de messages
MCP MCP tools/list (JSON) Tools exposés aux agents IA

Créer un Contrat

Saisie Manuelle

  1. Naviguez vers votre projet
  2. Ouvrez l'onglet Contrats d'API
  3. Cliquez sur Nouveau Contrat
  4. Remplissez les détails du contrat :
    • Nom — Un nom descriptif (ex. "API du Service Utilisateur")
    • Type — HTTP, gRPC, GraphQL, Async ou MCP
    • Version — Version sémantique (ex. 1.0.0)
    • Endpoint — URL de base de l'API
    • Description — Ce que fait l'API
  5. Collez ou écrivez le contenu de la spécification dans l'éditeur
  6. Cliquez sur Créer

Synchronisation Git

Au lieu de maintenir les contrats manuellement, vous pouvez les synchroniser depuis un dépôt git :

  1. Cliquez sur Nouveau Contrat et sélectionnez Git comme type de source
  2. Choisissez un dépôt connecté
  3. Spécifiez le chemin du fichier de spec (ex. api/openapi.yaml)
  4. Définissez la branche à suivre (par défaut, la branche principale du dépôt)
  5. Archyl récupère le contenu de la spec et le maintient synchronisé

Vous pouvez aussi utiliser des patterns glob pour correspondre à plusieurs fichiers. Par exemple, api/**/*.yaml correspondra à tous les fichiers YAML sous le répertoire api/.

Comportement de Synchronisation

  • Les specs sont récupérées du dépôt lors de la création du contrat
  • Utilisez le bouton Sync pour récupérer manuellement la dernière version
  • L'horodatage de la dernière synchronisation est affiché sur la carte du contrat

Serveurs MCP

Les serveurs MCP (Model Context Protocol) exposent des tools aux agents IA — chacun avec un nom, une description et un JSON Schema pour ses entrées. Cette surface de tools est aussi un contrat : elle définit ce qu'un agent a le droit de faire. Archyl la documente via le type de contrat MCP.

Contrairement aux autres types, les tools d'un serveur MCP ne sont généralement pas un fichier dans un dépôt — la liste qui fait autorité n'existe qu'au runtime, via l'appel tools/list. Les contrats MCP proposent donc deux sources.

Coller la liste des tools

  1. Cliquez sur Nouveau Contrat et choisissez MCP
  2. Gardez la source sur Manuel
  3. Collez le JSON tools/list du serveur — un objet de la forme { "tools": [ ... ] }
  4. Cliquez sur Créer

Archyl valide le document et affiche chaque tool.

Découvrir depuis un endpoint live

Laissez Archyl récupérer les tools directement depuis un serveur en cours d'exécution :

  1. Cliquez sur Nouveau Contrat, choisissez MCP, et sélectionnez Live endpoint comme source
  2. Saisissez l'URL du serveur et choisissez le transport (HTTP ou SSE)
  3. Si le serveur exige une authentification, choisissez où va le token — un header (ex. X-API-Key) ou un paramètre d'URL — et saisissez le token
  4. Cliquez sur Découvrir les tools — Archyl se connecte, effectue le handshake et liste chaque tool et ses paramètres
  5. Vérifiez les tools découverts, puis cliquez sur Créer

Pour rafraîchir les tools plus tard, éditez le contrat et relancez Découvrir les tools.

La découverte s'exécute dans votre navigateur, pas sur les serveurs d'Archyl. Votre token ne quitte jamais votre navigateur — Archyl stocke les tools découverts et les détails de connexion (URL, transport, nom du header/paramètre) mais jamais le token lui-même. Comme l'appel provient de votre machine, il peut aussi atteindre des serveurs sur localhost ou votre réseau privé.

La seule exigence : le serveur MCP doit autoriser l'origine de ce site (CORS) pour que votre navigateur puisse lire la réponse. Pour les serveurs que vous contrôlez, c'est un petit changement de config ; sinon, utilisez l'option « coller » ci-dessus.

Le visualiseur de tools MCP

Chaque tool est affiché avec son nom, sa description et ses paramètres d'entrée (dérivés de son JSON Schema), le schéma brut étant accessible par tool. Comme les autres types de contrats, le visualiseur est en lecture seule et reflète la liste de tools stockée.

Lier les Contrats à l'Architecture

Les contrats d'API prennent tout leur sens lorsqu'ils sont liés aux éléments C4 qu'ils décrivent. Un contrat peut être lié à des systèmes, conteneurs, composants ou éléments de code.

Ajouter des Liens

  1. Ouvrez la page de détail d'un contrat
  2. Cliquez sur Lier à un Élément
  3. Sélectionnez le niveau C4 (Système, Conteneur, Composant ou Code)
  4. Choisissez l'élément cible
  5. Le lien apparaît à la fois sur le contrat et dans le panneau de détail de l'élément

Voir les Contrats Liés

Sur le diagramme, faites un clic droit sur n'importe quel élément pour ouvrir son panneau de détail. Les contrats d'API liés apparaissent dans la section Contrats avec :

  • Nom et version du contrat
  • Badge du type de protocole (HTTP, gRPC, GraphQL, Async, MCP)
  • Lien vers la spécification complète

Entrées Serveur

Chaque contrat peut définir plusieurs entrées serveur — utile pour documenter différents environnements ou régions.

Champ Description
URL L'URL de base du serveur (ex. https://api.example.com/v1)
Description Environnement ou usage (ex. "Production", "Staging")

Le Visualiseur de Spécifications

Archyl affiche vos spécifications d'API avec un visualiseur interactif :

  • OpenAPI — Endpoints groupés par tag, avec schémas requête/réponse, paramètres et exemples
  • gRPC — Définitions de services, méthodes RPC et types de messages
  • GraphQL — Types, requêtes, mutations et souscriptions
  • AsyncAPI — Canaux, messages et schémas
  • MCP — Tools, chacun avec sa description et ses paramètres d'entrée (depuis son JSON Schema)

Le visualiseur est en lecture seule et reflète toujours le contenu actuel du contrat.

Canaux d'Événements

Les canaux d'événements documentent le côté messagerie asynchrone de votre architecture — topics Kafka, files SQS, exchanges RabbitMQ, et similaires.

Créer un Canal d'Événements

  1. Naviguez vers votre projet
  2. Ouvrez l'onglet Canaux d'Événements
  3. Cliquez sur Nouveau Canal
  4. Configurez le canal :
Champ Description
Nom Nom du canal (ex. "Événements de Commande Créée")
Direction produce ou consume
Type de Broker Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar ou Custom
Nom du Topic Le nom réel du topic ou de la file
Format de Schéma JSON Schema, Avro, Protobuf ou Text
Schéma de Valeur La définition du schéma de payload de l'événement

Liaison à l'Architecture

Les canaux d'événements suivent le même modèle de liaison que les contrats d'API. Liez un canal aux systèmes, conteneurs ou composants qui produisent ou consomment ses événements. Cela rend les flux de messages visibles directement sur le diagramme d'architecture.

Bonnes Pratiques

Gardez les Specs à Jour

  • Utilisez la synchronisation git pour les specs qui vivent dans votre codebase
  • Versionnez vos contrats avec le versionnage sémantique
  • Mettez à jour le contrat quand l'API change

Liez Tout

  • Chaque conteneur servant une API devrait avoir au moins un contrat lié
  • Liez les canaux d'événements aux producteurs et aux consommateurs
  • Utilisez les liens pour rendre le diagramme auto-documenté

Organisez par Service

  • Un contrat par service ou contexte borné
  • Utilisez des noms descriptifs cohérents avec le nommage de votre architecture
  • Incluez la version de l'API dans le champ version du contrat

Documentez les Serveurs

  • Ajoutez des entrées serveur pour chaque environnement
  • Incluez les endpoints internes et externes
  • Gardez les URLs à jour quand l'infrastructure change

Prochaines Étapes