Artikelen
Een interne API-catalogus bouwen met Atlassian Compass
KATIE SILVER
PRINCIPAL PRODUCT MANAGER, ATLASSIAN
Managementsamenvatting
Managementsamenvatting komt hier
Tijd
Vier minuten lezen. Minder dan tien minuten om Compass in te stellen.
Doelgroep
Je maakt deel uit van een softwareleveringsteam en gebruikt API's. Ontwikkelaars, engineers en anderen kunnen er allemaal baat bij hebben.
Vereisten
- Compass: je kunt het gratis proberen en bent binnen een paar minuten aan de slag.
Het bouwen van een nauwkeurige API-catalogus is lastig
In het afgelopen decennium hebben we grote monolieten ingeruild voor microservices, gedistribueerde architecturen en autonome teams. Er zijn echte voordelen, maar je kunt niet om de gevolgen heen. Getypte compilers en tests worden gebruikt om alle onderdelen van een grote codebase goed samen te laten werken. Tegenwoordig zijn de grenzen API's, en het is niet duidelijk of ze allemaal goed samen zullen werken zodra ze zijn geïmplementeerd.
We weten dat ontwikkelaars sneller werken en teams betere producten leveren wanneer iedereen begrijpt hoe de API's werken en wanneer ze veranderen. Het bijhouden en onderhouden van de documentatie is moeilijk.
Elke organisatie bevindt zich op een ander volwassenheidsniveau als het gaat om het in kaart brengen van hun services. Bij sommige teams zorgen gesprekken op Slack voor afstemming tussen de API-producenten en -gebruikers. Bij andere teams wordt de werking van elke API vastgelegd wanneer de service wordt gecreëerd, maar nooit bijgewerkt. Als je goede processen of tools hebt, is elke API gedocumenteerd en worden de veranderingen automatisch gecommuniceerd naar de andere belanghebbenden.
Waar je je ook bevindt in dat traject, Compass, het nieuwe ontwikkelaarsplatform van Atlassian, kan helpen.
Gecentraliseerde API-documentatie met Compass
Welke plaats heeft API-documentatie in de wereld van microservices? Dat we onze services apart maken en implementeren, betekent niet dat we willen dat elke service een eigen gehoste documentatiesite heeft, of een OpenAPI-bestand dat op een obscure locatie staat. Teams willen al die informatie samenbrengen en doorzoekbaar maken, zonder een enorme interne inspanning om een API-register op te bouwen.
Compass maakt het eenvoudig om al je API-documentatie binnen een uur te centraliseren, en niet binnen een week of een kwartaal. Je hoeft documentatie niet elke keer handmatig te uploaden wanneer je een verandering aanbrengt, je hoeft alleen je SCM (Bitbucket, GitHub of GitLab) te verbinden met Compass.
Binnen een paar minuten doorzoekt Compass al je repo's naar OpenAPI-bestanden en publiceert ze naar je catalogus. Alle API's van al je teams worden direct gecentraliseerd en doorzoekbaar.
API's ontdekken en integreren
Stel je voor dat een ontwikkelaar een ticket oppakt voor het maken van een nieuwe terugbetalingsflow. Hij weet dat hij de juiste API moet vinden om een terugbetaling te verwerken, maar hij weet niet waar hij moet beginnen. Bij veel bedrijven zou hij vragen stellen op Slack en mogelijk uren wachten tot een collega aan de andere kant van de wereld de vragen beantwoordt over welke API moet worden gebruikt. In teams met Compass kan dit allemaal als selfservice worden uitgevoerd. Ontwikkelaars kunnen zoeken naar API-eindpunten en de exacte informatie vinden die ze nodig hebben, rechtstreeks in Compass in slechts een paar seconden. Dat betekent dat de ontwikkelaar die naar informatie zoekt deze sneller vindt, en het team dat eigenaar is van de betreffende API minder onderbrekingen ervaart.
Ontvang meldingen over API-veranderingen
In de wereld van microservices wordt elke service autonoom geïmplementeerd, soms met veranderingen waar de gebruikers van op de hoogte moeten zijn. Gelukkig weet Compass niet alleen alles over je API-documentatie, maar ook over hoe je API in de loop van de tijd verandert. Elke keer dat een collega een pull request samenvoegt waardoor je API-documentatie wordt bijgewerkt, werkt Compass ook zijn versie van de documentatie bij, zodat de versie die ontwikkelaars in Compass zien altijd de meest actuele API is.
Historische veranderingen worden zelfs weergegeven op de wijzigingslogpagina, zodat je kunt zien wanneer belangrijke veranderingen in het verleden hebben plaatsgevonden.
Wanneer ontwikkelaars de documentatie hebben die ze nodig hebben, wordt code sneller geleverd
In Postman's recente API-ontwikkelaarsenquête gaf 52% van de ontwikkelaars aan dat het grootste probleem waarmee zij te maken hadden bij het werken met API's ontbrekende documentatie was. Ontbrekende documentatie maakt het ontwikkelingsproces langzamer, het onboarden van nieuwe engineers uitdagender en software minder betrouwbaar.
Als je je eigen interne API-catalogus moest bouwen, zou dat een enorm project zijn, met veel bewegende onderdelen. We hebben al dat werk voor je gedaan; een gecentraliseerde documentatiehub kost je slechts enkele minuten tijd.
Geef je team de informatie die ze nodig hebben en zie ze sneller leveren 🚀.