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 et AsyncAPI, avec synchronisation git optionnelle.
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 |
Créer un Contrat
Saisie Manuelle
- Naviguez vers votre projet
- Ouvrez l'onglet Contrats d'API
- Cliquez sur Nouveau Contrat
- Remplissez les détails du contrat :
- Nom — Un nom descriptif (ex. "API du Service Utilisateur")
- Type — HTTP, gRPC, GraphQL ou Async
- Version — Version sémantique (ex.
1.0.0) - Endpoint — URL de base de l'API
- Description — Ce que fait l'API
- Collez ou écrivez le contenu de la spécification dans l'éditeur
- Cliquez sur Créer
Synchronisation Git
Au lieu de maintenir les contrats manuellement, vous pouvez les synchroniser depuis un dépôt git :
- Cliquez sur Nouveau Contrat et sélectionnez Git comme type de source
- Choisissez un dépôt connecté
- Spécifiez le chemin du fichier de spec (ex.
api/openapi.yaml) - Définissez la branche à suivre (par défaut, la branche principale du dépôt)
- 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
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
- Ouvrez la page de détail d'un contrat
- Cliquez sur Lier à un Élément
- Sélectionnez le niveau C4 (Système, Conteneur, Composant ou Code)
- Choisissez l'élément cible
- 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)
- 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
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
- Naviguez vers votre projet
- Ouvrez l'onglet Canaux d'Événements
- Cliquez sur Nouveau Canal
- 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
- Canaux d'Événements — Documentez la messagerie asynchrone
- Demandes de Changement d'Architecture — Proposez des modifications à votre architecture
- Gestion des Releases — Suivez les déploiements à travers vos systèmes