Creazione di un catalogo delle API interno con Atlassian Compass
KATIE SILVER
PRINCIPAL PRODUCT MANAGER, ATLASSIAN
Riepilogo esecutivo
Il riepilogo esecutivo va qui
Durata
Quattro minuti per la lettura. Meno di 10 minuti per la configurazione di Compass.
Destinatari
Fai parte di un team di distribuzione del software e usi le API. Possono trarne vantaggio sviluppatori, ingegneri e altre figure.
Prerequisiti
- Ottieni Compass: la prova è gratuita e richiede pochi minuti per iniziare.
La creazione di un catalogo delle API accurato è un compito arduo
Nell'ultimo decennio, abbiamo sostituito i grandi monoliti con microservizi, architetture distribuite e team autonomi. I vantaggi sono concreti, ma lo sono anche le conseguenze. Per fare in modo che tutte le parti di una grande base di codice funzionassero bene insieme si utilizzavano compilatori tipizzati e test. Oggi invece i confini sono le API e non è chiaro se funzioneranno correttamente insieme una volta distribuite.
Sappiamo che gli sviluppatori si muovono più velocemente e che i team rilasciano prodotti migliori quando tutti comprendono come funzionano le API e quando subiscono modifiche. Ciò che risulta difficile è monitorare e gestire quel tipo di documentazione.
Quando si tratta di mappare i servizi, ogni organizzazione si trova a un livello di maturità diverso. In alcuni team, le conversazioni su Slack favoriscono l'allineamento tra chi produce e chi utilizza le API. In altri team, il modo in cui funziona ogni API viene documentato alla creazione del servizio ma non viene mai aggiornato. Se hai in atto processi o strumenti validi, ogni API è documentata e le sue modifiche vengono comunicate automaticamente agli altri stakeholder.
Ovunque ti trovi in questo percorso, Compass, la nuova piattaforma per sviluppatori di Atlassian, può aiutarti.
Documentazione API centralizzata con Compass
Dove dovrebbe risiedere la documentazione delle API nel mondo dei microservizi? Il fatto che creiamo e distribuiamo i nostri servizi separatamente non significa che desideriamo che ogni servizio abbia il proprio sito di documentazione in hosting, oppure un file OpenAPI che si trova in una posizione non nota. I team vogliono riunire tutte queste informazioni e fare in modo che possano essere cercate senza un enorme sforzo interno per creare un registro delle API.
Compass permette di centralizzare facilmente tutta la documentazione delle API in un'ora, non in una settimana o in un trimestre. Non è necessario caricare manualmente la documentazione ogni volta che apporti una modifica, devi solo collegare il tuo SCM (Bitbucket, GitHub o GitLab) a Compass.
Nel giro di pochi minuti Compass analizzerà tutti i tuoi repository per trovare i file OpenAPI e li pubblicherà nel tuo catalogo. Tutte le API di tutti i tuoi team diventeranno immediatamente centralizzate e ricercabili.
Individuazione e integrazione con un'API
Immagina che uno sviluppatore prenda in carico un ticket per creare un nuovo flusso di rimborso. Sa di dover trovare l'API corretta da utilizzare per elaborare un rimborso, ma non sa da dove iniziare. In molte aziende, chiederebbe in giro su Slack e probabilmente aspetterebbe ore che un collega dall'altra parte del mondo risponda alle sue domande su quale API utilizzare. Nei team con Compass, tutto questo può essere gestito in modalità self-service. Gli sviluppatori possono cercare gli endpoint delle API e trovare direttamente in Compass, in pochi secondi, le informazioni esatte di cui hanno bisogno. Questo significa che chi sviluppa e cerca informazioni le trova più velocemente e il team che possiede l'API in questione subisce meno interruzioni.
Ricevi notifiche sulle modifiche alle API
Nel mondo dei microservizi, ogni servizio viene distribuito autonomamente, a volte passando a modalità di cui i consumatori devono essere a conoscenza. Fortunatamente Compass non conosce solo la documentazione delle tue API, ma sa anche come le tue API cambiano nel tempo. Ogni volta che un collega unisce una richiesta pull che aggiorna la documentazione delle tue API, Compass aggiorna anche la sua versione della documentazione, in modo che la versione che gli sviluppatori vedono in Compass sia sempre l'API più aggiornata.
La cronologia delle modifiche viene visualizzata anche nella pagina del log delle modifiche, così puoi vedere quando sono avvenute importanti modifiche in passato.
Quando gli sviluppatori hanno a disposizione la documentazione di cui hanno bisogno, il codice viene rilasciato più velocemente
In un recente sondaggio di Postman per sviluppatori di API, il 52% degli intervistati ha dichiarato che il problema più grande che ha dovuto affrontare lavorando con le API è stato la mancanza di documentazione, che rallenta lo sviluppo, rende più difficile l'onboarding di nuovi ingegneri e riduce l'affidabilità del software.
Se dovessi creare il tuo catalogo delle API interno, si tratterebbe di un progetto enorme, con molti elementi variabili. Abbiamo pensato noi a fare tutto questo lavoro per te, con un hub di documentazione centralizzato disponibile in pochi minuti.
Fornisci al tuo team le informazioni di cui ha bisogno e guarda come il rilascio diventa più veloce 🚀.