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, AsyncAPI e MCP, con sincronizzazione opzionale da git o scoperta live.

Tipi di Contratto Supportati

Creare un Contratto

Inserimento Manuale

1. Naviga al tuo progetto
2. Apri la scheda Contratti API
3. Clicca su Nuovo Contratto
4. Compila i dettagli del contratto:
   • Nome — Un nome descrittivo (es. "API User Service")
   • Tipo — HTTP, gRPC, GraphQL, Async o MCP
   • Versione — Versione semantica (es. 1.0.0)
   • Endpoint — URL base dell'API
   • Descrizione — Cosa fa l'API
5. Incolla o scrivi il contenuto della specifica nell'editor
6. Clicca su Crea

Sincronizzazione Git

Invece di mantenere i contratti manualmente, puoi sincronizzarli da un repository git:

1. Clicca su Nuovo Contratto e seleziona Git come tipo di sorgente
2. Scegli un repository connesso
3. Specifica il percorso del file della specifica (es. api/openapi.yaml)
4. Imposta il branch da tracciare (predefinito: branch principale del repository)
5. 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

Server MCP

I server MCP (Model Context Protocol) espongono tool agli agenti IA — ognuno con un nome, una descrizione e un JSON Schema per i suoi input. Questa superficie di tool è anch'essa un contratto: definisce cosa un agente ha il permesso di fare. Archyl la documenta come tipo di contratto MCP.

A differenza degli altri tipi, i tool di un server MCP di solito non sono un file in un repository — l'elenco autorevole esiste solo a runtime, tramite la chiamata tools/list. Per questo i contratti MCP supportano due sorgenti.

Incollare l'elenco dei tool

1. Clicca su Nuovo Contratto e scegli MCP
2. Mantieni la sorgente su Manuale
3. Incolla il JSON tools/list del server — un oggetto della forma { "tools": [ ... ] }
4. Clicca su Crea

Archyl convalida il documento e renderizza ogni tool.

Scoprire da un endpoint live

Lascia che Archyl recuperi i tool direttamente da un server in esecuzione:

1. Clicca su Nuovo Contratto, scegli MCP e seleziona Live endpoint come sorgente
2. Inserisci l'URL del server e scegli il transport (HTTP o SSE)
3. Se il server richiede autenticazione, scegli dove va il token — un header (es. X-API-Key) o un parametro URL — e inserisci il token
4. Clicca su Scopri i tool — Archyl si connette, esegue l'handshake ed elenca ogni tool e i suoi parametri
5. Verifica i tool scoperti, poi clicca su Crea

Per aggiornare i tool in seguito, modifica il contratto ed esegui di nuovo Scopri i tool.

La scoperta viene eseguita nel tuo browser, non sui server di Archyl. Il tuo token non lascia mai il tuo browser — Archyl memorizza i tool scoperti e i dettagli di connessione (URL, transport, nome dell'header/parametro) ma mai il token stesso. Poiché la chiamata parte dalla tua macchina, può anche raggiungere server su localhost o nella tua rete privata.

L'unico requisito: il server MCP deve consentire l'origine di questo sito (CORS) affinché il tuo browser possa leggere la risposta. Per i server che controlli è una piccola modifica di configurazione; altrimenti, usa l'opzione "incolla" qui sopra.

Il visualizzatore di tool MCP

Ogni tool è mostrato con il suo nome, la descrizione e i parametri di input (derivati dal suo JSON Schema), con lo schema grezzo disponibile per ciascun tool. Come gli altri tipi di contratto, il visualizzatore è in sola lettura e riflette l'elenco di tool memorizzato.

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

1. Apri la pagina di dettaglio di un contratto
2. Clicca su Collega a Elemento
3. Seleziona il livello C4 (Sistema, Container, Componente o Codice)
4. Scegli l'elemento di destinazione
5. 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, MCP)
• Link alla specifica completa

Voci Server

Ogni contratto può definire più voci server — utile per documentare diversi ambienti o regioni.

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
• MCP — Tool, ciascuno con la sua descrizione e i parametri di input (dal suo JSON Schema)

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

1. Naviga al tuo progetto
2. Apri la scheda Canali di Eventi
3. Clicca su Nuovo Canale
4. Configura il canale:

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