Contratti API: Le Tue Specifiche API, Collegate alla Tua Architettura
Qualche settimana fa stavo revisionando un'architettura di sistema con un team che aveva un bellissimo diagramma C4. I container erano ben definiti. Le relazioni avevano etichette chiare. Tutto sembrava perfetto — finche qualcuno non ha chiesto "com'e fatta l'API tra il Servizio Ordini e il Gateway di Pagamento?"
Silenzio. Il diagramma diceva "REST/JSON." La specifica OpenAPI viveva in un altro repository. L'elenco effettivo degli endpoint era in una pagina Notion che non veniva aggiornata da quando l'ultimo stagista se n'era andato. Tre fonti di verita per una superficie API, e nessuna di esse concordava.
Questo e assurdamente comune. Le specifiche API sono tra gli artefatti piu precisi e leggibili dalle macchine in un codebase. Eppure nella documentazione dell'architettura sono invisibili. Hai una scatola, una freccia e un'etichetta di protocollo. Il contratto effettivo — gli endpoint, gli schema, i campi — vive da un'altra parte.
Abbiamo costruito i Contratti API per risolvere questo problema. Le tue specifiche API ora vivono dentro la tua architettura, collegate agli elementi che le implementano e le consumano.
Quattro Protocolli, Una Casa
I sistemi moderni raramente parlano un singolo protocollo. La tua API pubblica e REST, i tuoi servizi interni comunicano via gRPC, e il tuo frontend recupera dati tramite GraphQL. Ciascuno ha il proprio formato di specifica, i propri strumenti, il proprio ecosistema di documentazione.
I Contratti API di Archyl supportano tutti e quattro:
OpenAPI / Swagger — Importa le tue specifiche OpenAPI 3.x o Swagger 2.0 e ottieni un visualizzatore di riferimento interattivo alimentato da Scalar. Gli endpoint sono raggruppati, i parametri documentati, gli schema espandibili. E la stessa esperienza che otterresti da uno strumento dedicato di documentazione API, incorporata direttamente nel tuo workspace architetturale.
gRPC / Protocol Buffers — Incolla o sincronizza le tue definizioni .proto. Il visualizzatore renderizza servizi, metodi, tipi di messaggio ed enum con evidenziazione della sintassi e indentazione corretta. Basta cercare nei file proto per capire cosa espone un servizio.
GraphQL — Importa il tuo schema ed esplora tipi, query, mutation e subscription. E se hai configurato endpoint del server, ottieni un playground GraphiQL completo — scrivi query, eseguile contro la tua API reale ed esplora lo schema interattivamente, tutto senza lasciare Archyl.
AsyncAPI — Definisci le tue API event-driven con specifiche AsyncAPI. Il visualizzatore renderizza canali, operazioni, schema dei messaggi e binding del server con evidenziazione completa della sintassi. Che tu stia usando Kafka, RabbitMQ, NATS o WebSocket, i contratti AsyncAPI documentano quali eventi i tuoi servizi producono e consumano.
Importa da Git o Incolla Direttamente
Le specifiche API cambiano. Un endpoint viene aggiunto, un campo viene deprecato, una nuova versione viene rilasciata. Se la tua documentazione richiede copia-incolla manuale per restare aggiornata, non restera aggiornata.
Per questo i Contratti API supportano due modalita di origine:
Sincronizzazione Git collega il tuo contratto a un file di specifica in un repository. Puntalo al tuo openapi.yaml, al tuo service.proto, al tuo schema.graphql o al tuo asyncapi.yaml, e Archyl recupera il contenuto direttamente. Quando la specifica cambia a monte, clicca sincronizza e il contratto si aggiorna. Funziona con ogni provider git supportato da Archyl — GitHub, GitLab, Bitbucket, Azure DevOps e istanze self-hosted.
Manuale e per i team che non tengono le specifiche in git, o per la prototipazione rapida. Incolla il contenuto della specifica direttamente e modificalo sul posto. Utile per abbozzare un contratto prima che il servizio esista, o per importare una specifica da un'API di terze parti che non controlli.
Entrambe le modalita supportano il versioning, cosi puoi tracciare quale versione del contratto stai documentando.
Collegato alla Tua Architettura
Ecco dove i Contratti API diventano piu di un visualizzatore di specifiche.
Ogni contratto puo essere collegato a uno o piu elementi C4 — sistemi, container, componenti o elementi di codice. Una specifica OpenAPI puo essere collegata al container API Gateway che la serve. Un proto gRPC puo essere collegato al componente microservizio che lo implementa. Uno schema GraphQL puo essere collegato al BFF (Backend for Frontend) che lo espone.
Questi link sono bidirezionali. Dal contratto, vedi quali elementi architetturali si relazionano ad esso. Dal pannello dettagli dell'elemento sul diagramma, vedi quali contratti descrivono la sua superficie API. Quando fai clic destro su un container nel canvas, puoi collegare e scollegare contratti direttamente dal menu contestuale.
Questo colma il divario che ho descritto all'inizio. Quando qualcuno chiede "com'e fatta l'API tra questi due servizi?", la risposta e a un clic di distanza. Non in uno strumento diverso, non in un repo diverso — proprio li sul diagramma.
Canali di Eventi
Le architetture event-driven sono notoriamente difficili da documentare. Quale servizio pubblica su quale topic? Qual e lo schema del messaggio? Chi lo consuma?
I Canali di Eventi di Archyl portano visibilita alla comunicazione asincrona. Ogni contratto AsyncAPI espone automaticamente i canali che definisce — topic, code, stream — e li mappa sugli elementi C4 che producono e consumano eventi.
Sul diagramma, i canali di eventi appaiono come tipi di connessione distinti, rendendo immediatamente chiaro quali relazioni sono chiamate API sincrone e quali sono flussi di eventi asincroni. Questo e critico per capire il comportamento del sistema: una chiamata REST tra due servizi ha caratteristiche di affidabilita e accoppiamento molto diverse da un evento pubblicato su un message broker.
Puoi anche creare canali di eventi indipendentemente dai contratti AsyncAPI, utile per documentare sistemi di messaggistica legacy o protocolli proprietari che non hanno una specifica formale.
Visualizzatori Interattivi
Non volevamo che i contratti fossero blocchi di testo grezzo. Ogni protocollo ottiene un visualizzatore costruito appositamente:
Il visualizzatore OpenAPI renderizza un riferimento API completamente interattivo. Gli endpoint sono organizzati per tag, con schema di richiesta/risposta espandibili, documentazione dei parametri e dettagli di autenticazione. Se hai definito URL del server, il visualizzatore li mostra cosi gli sviluppatori sanno dove inviare le richieste. E un'esperienza reale di documentazione API, non un dump YAML con evidenziazione della sintassi.
Il visualizzatore Protocol Buffer renderizza le definizioni proto con colorazione della sintassi appropriata, rendendo servizi, RPC e strutture dei messaggi facili da scansionare.
Il visualizzatore GraphQL evidenzia tipi, campi e direttive. E quando hai configurato un endpoint del server, una seconda scheda apre un playground GraphiQL completo. Puoi scrivere ed eseguire query contro la tua API live, esplorare lo schema tramite introspezione e testare mutation — tutto incorporato in Archyl. Se la tua API GraphQL ha piu ambienti (staging, produzione), puoi definire piu voci server e alternare tra di essi.
Il visualizzatore AsyncAPI renderizza le definizioni delle tue API event-driven con elenchi di canali, schema dei messaggi e configurazioni server/broker. Ogni canale mostra le sue operazioni (pubblica/sottoscrivi), schema del payload e binding — dando agli sviluppatori un quadro chiaro della tua superficie di comunicazione event-driven.
Come Iniziare
Naviga in qualsiasi progetto e apri la sezione Contratti API dalla sidebar. Clicca "Aggiungi Contratto" e scegli il tipo di protocollo e la modalita di origine.
Per i contratti da git, collega un repository (o riutilizzane uno gia collegato al tuo progetto), specifica il percorso del file e il branch, e Archyl recupera la specifica. Per i contratti manuali, incolla il contenuto direttamente.
Una volta creato, vai al diagramma e collega il contratto agli elementi C4 rilevanti. Da quel punto in poi, chiunque esplori l'architettura puo approfondire la superficie API effettiva dal diagramma stesso.
Perche Questo e Importante
I diagrammi architetturali sono potenti per mostrare la struttura — cosa esiste e come le cose si connettono. Ma sono sempre stati deboli sulle interfacce. Una freccia di relazione etichettata "REST/HTTPS" dice quasi nulla su cosa fluisce effettivamente tra due servizi. Un evento pubblicato su un topic Kafka e ancora piu opaco — a meno che tu non abbia la specifica AsyncAPI e il mapping dei canali proprio li.
I contratti API colmano quel divario. Aggiungono precisione alle frecce. Quando un nuovo membro del team guarda la tua architettura e vede una connessione tra l'App Mobile e l'API Gateway, puo immediatamente aprire la specifica OpenAPI e capire esattamente quali endpoint sono disponibili, quali strutture dati vengono scambiate e quale autenticazione e richiesta.
Questa e documentazione architetturale che si guadagna il suo spazio. Non perche qualcuno l'ha imposta, ma perche risponde a domande reali che emergono ogni giorno.
Stai gia usando Archyl per la tua architettura? Esplora la funzionalita Contratti API nel tuo progetto. Nuovo sulla piattaforma? Scopri il modello C4 e come la scoperta con IA puo generare automaticamente il tuo diagramma architetturale.