Contratti API
I Contratti API ti permettono di allegare specifiche API ai tuoi elementi architetturali, mantenendo documentazione e design sincronizzati. Archyl supporta contratti OpenAPI (REST), gRPC, GraphQL e AsyncAPI, con sincronizzazione opzionale da git.
Tipi di Contratto Supportati
| Tipo | Formato | Caso d'Uso |
|---|---|---|
| HTTP (REST) | OpenAPI 3.x (YAML/JSON) | API REST, webhook |
| gRPC | Protocol Buffers (.proto) | RPC servizio-a-servizio |
| GraphQL | GraphQL SDL (.graphql) | API di query |
| Async | AsyncAPI (YAML/JSON) | API event-driven, code messaggi |
Creare un Contratto
Inserimento Manuale
- Naviga al tuo progetto
- Apri la scheda Contratti API
- Clicca su Nuovo Contratto
- Compila i dettagli del contratto:
- Nome — Un nome descrittivo (es. "API User Service")
- Tipo — HTTP, gRPC, GraphQL o Async
- Versione — Versione semantica (es.
1.0.0) - Endpoint — URL base dell'API
- Descrizione — Cosa fa l'API
- Incolla o scrivi il contenuto della specifica nell'editor
- Clicca su Crea
Sincronizzazione Git
Invece di mantenere i contratti manualmente, puoi sincronizzarli da un repository git:
- Clicca su Nuovo Contratto e seleziona Git come tipo di sorgente
- Scegli un repository connesso
- Specifica il percorso del file della specifica (es.
api/openapi.yaml) - Imposta il branch da tracciare (predefinito: branch principale del repository)
- Archyl preleva il contenuto della specifica e lo mantiene sincronizzato
Puoi anche usare pattern glob per abbinare più file. Ad esempio, api/**/*.yaml corrisponderà a tutti i file YAML nella directory api/.
Comportamento della Sincronizzazione
- Le specifiche vengono recuperate dal repository quando il contratto viene creato
- Usa il pulsante Sincronizza per prelevare manualmente l'ultima versione
- Il timestamp dell'ultima sincronizzazione viene visualizzato sulla scheda del contratto
Collegare i Contratti all'Architettura
I contratti API diventano significativi quando collegati agli elementi C4 che descrivono. Un contratto può essere collegato a sistemi, container, componenti o elementi di codice.
Aggiungere Collegamenti
- Apri la pagina di dettaglio di un contratto
- Clicca su Collega a Elemento
- Seleziona il livello C4 (Sistema, Container, Componente o Codice)
- Scegli l'elemento di destinazione
- Il collegamento appare sia nel contratto che nel pannello dettagli dell'elemento
Visualizzare i Contratti Collegati
Nel diagramma, fai clic destro su qualsiasi elemento per aprire il pannello dettagli. I contratti API collegati appaiono nella sezione Contratti con:
- Nome e versione del contratto
- Badge del tipo di protocollo (HTTP, gRPC, GraphQL, Async)
- Link alla specifica completa
Voci Server
Ogni contratto può definire più voci server — utile per documentare diversi ambienti o regioni.
| Campo | Descrizione |
|---|---|
| URL | L'URL base del server (es. https://api.example.com/v1) |
| Descrizione | Ambiente o scopo (es. "Produzione", "Staging") |
Il Visualizzatore di Specifiche
Archyl renderizza le tue specifiche API con un visualizzatore interattivo:
- OpenAPI — Endpoint raggruppati per tag, con schemi di richiesta/risposta, parametri ed esempi
- gRPC — Definizioni di servizio, metodi RPC e tipi di messaggio
- GraphQL — Tipi, query, mutation e subscription
- AsyncAPI — Canali, messaggi e schemi
Il visualizzatore è in sola lettura e riflette sempre il contenuto corrente del contratto.
Canali di Eventi
I canali di eventi documentano il lato di messaggistica asincrona della tua architettura — topic Kafka, code SQS, exchange RabbitMQ e simili.
Creare un Canale di Eventi
- Naviga al tuo progetto
- Apri la scheda Canali di Eventi
- Clicca su Nuovo Canale
- Configura il canale:
| Campo | Descrizione |
|---|---|
| Nome | Nome del canale (es. "Eventi Ordine Creato") |
| Direzione | produce o consume |
| Tipo Broker | Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar o Personalizzato |
| Nome Topic | Il nome effettivo del topic o della coda |
| Formato Schema | JSON Schema, Avro, Protobuf o Testo |
| Schema Valore | La definizione dello schema del payload dell'evento |
Collegamento all'Architettura
I canali di eventi seguono lo stesso modello di collegamento dei contratti API. Collega un canale ai sistemi, container o componenti che producono o consumano i suoi eventi. Questo rende i flussi di messaggi visibili direttamente sul diagramma architetturale.
Best Practice
Mantieni le Specifiche Aggiornate
- Usa la sincronizzazione git per le specifiche che risiedono nel tuo codebase
- Versiona i contratti seguendo il versionamento semantico
- Aggiorna il contratto quando l'API cambia
Collega Tutto
- Ogni container che serve API dovrebbe avere almeno un contratto collegato
- Collega i canali di eventi sia ai produttori che ai consumatori
- Usa i collegamenti per rendere il diagramma auto-documentante
Organizza per Servizio
- Un contratto per servizio o bounded context
- Usa nomi descrittivi che corrispondano alla nomenclatura della tua architettura
- Includi la versione dell'API nel campo versione del contratto
Documenta i Server
- Aggiungi voci server per ogni ambiente
- Includi sia gli endpoint interni che quelli esterni
- Mantieni gli URL aggiornati al cambiare dell'infrastruttura
Prossimi Passi
- Canali di Eventi — Documentare la messaggistica asincrona
- Richieste di Modifica Architetturale — Proporre modifiche alla tua architettura
- Gestione delle Release — Tracciare i deploy attraverso i tuoi sistemi