Erstellen eines internen API-Katalogs mit Atlassian Compass
Katie Silver
PRINCIPAL PRODUCT MANAGER, ATLASSIAN
Zusammenfassung
Zusammenfassung hier einfügen
Zeit
Lesedauer: 4 Minuten. Das Einrichten von Compass dauert weniger als 10 Minuten.
Zielpublikum
Du bist Teil eines Software-Delivery-Teams und verwendest APIs. Die Zielgruppe sind Entwickler, Ingenieure und andere.
Voraussetzungen
- Du benötigst Compass. Die Testversion ist kostenlos und innerhalb weniger Minuten einsatzbereit.
Einen präzisen API-Katalog zu erstellen, ist eine echte Herausforderung
In den letzten zehn Jahren haben wir große monolithische Anwendungen gegen Microservices, verteilte Architekturen und autonome Teams eingetauscht. Das hatte viele Vorteile, aber auch Folgen. Typisierte Compiler und Tests sorgen dafür, dass alle Teile einer großen Codebasis reibungslos zusammenarbeiten. Heutzutage setzen APIs die Grenzen, und oft ist es unklar, ob sie nach einem Deployment miteinander kompatibel sein werden.
Wir wissen, dass Entwickler schneller vorankommen und Teams bessere Produkte auf den Markt bringen, wenn alle wissen, wie APIs funktionieren und wann sie sich ändern. Es ist die Dokumentation der APIs und ihrer Änderungen, die schwierig ist.
Jede Organisation hat einen anderen Reifegrad erreicht, wenn es um die Kartierung der von ihr verwendeten Services geht. Manche Teams nutzen Slack, um die Anforderungen von API-Providern und -Nutzern abzustimmen. Andere Teams dokumentieren ihre APIs einmalig bei der Serviceerstellung, danach aber nie wieder. Mit geeigneten Prozessen oder Tools lässt sich jede API gut dokumentieren und Änderungen werden automatisch an andere Stakeholder kommuniziert.
Wo auch immer du dich auf diesem Weg befindest – Compass, die neue Entwicklerplattform von Atlassian, kann dir helfen.
Zentrale API-Dokumentation mit Compass
Wo sollte API-Dokumentation in der Welt der Microservices vorgehalten werden? Nur weil wir Services separat erstellen und bereitstellen, heißt das nicht, dass wir für jeden Service eine eigene gehostete Dokumentationswebsite oder eine OpenAPI-Datei an einem obskuren Ort speichern müssen. Teams hätten diese Informationen gerne an einem Ort, am besten durchsuchbar, und ohne den enormen internen Aufwand für den Aufbau einer API-Registry.
Hier kommt Compass ins Spiel. Damit kannst du deine gesamte API-Dokumentation innerhalb einer Stunde zentralisieren, nicht in einer Woche oder einem Quartal. Du musst nicht jedes Mal manuell Dokumente hochladen, wenn du eine Änderung vornimmst. Du musst nur dein SCM (Bitbucket, GitHub oder GitLab) mit Compass verbinden.
In wenigen Minuten scannt Compass alle deine Repositorys nach OpenAPI-Dateien und veröffentlicht sie in deinem Katalog. Alle APIs sämtlicher Teams werden sofort zentralisiert und durchsuchbar.
APIs finden und integrieren
Angenommen, ein Entwickler nimmt sich ein Ticket vor, um einen neuen Erstattungsablauf zu erstellen. Zur Verarbeitung der Rückerstattung wird eine API benötigt, aber welche, das weiß der Entwickler nicht. In vielen Unternehmen wäre Slack die erste Anlaufstelle. Möglicherweise wartet der Entwickler stundenlang, bis ein Kollege auf der anderen Seite der Welt ihm mitteilt, welche API die richtige ist. In Teams mit Compass geht das ganz von alleine mit Self-Service. Entwickler können nach API-Endpunkten suchen und die genauen Informationen, die sie benötigen, direkt in Compass in nur wenigen Sekunden finden. Entwickler finden Informationen schneller und das Team, in dessen Zuständigkeit die API fällt, ist nicht mit ständigen Unterbrechungen konfrontiert.
Benachrichtigungen zu API-Änderungen erhalten
In einer Microservices-Welt wird jeder Service autonom bereitgestellt und ändert sich manchmal auf eine Weise, über die Nutzer Bescheid wissen müssen. Zum Glück weiß Compass nicht nur, wo sich deine API-Dokumentation befindet, sondern auch, wie sich deine API im Laufe der Zeit verändert. Jedes Mal, wenn ein Kollege den Merge einer Pull-Anfrage durchführt, um die API-Dokumenten zu aktualisieren, aktualisiert Compass auch die Dokumentation, sodass die Version, die Entwickler in Compass sehen, immer die aktuellste API ist.
Frühere Änderungen werden im Änderungsprotokoll angezeigt, sodass du sehen kannst, wann wichtige Änderungen stattgefunden haben.
Wenn Entwickler über die richtige Dokumentation verfügen, wird Code schneller ausgeliefert
In Postmans aktueller API-Entwickler-Umfrage gaben 52 % der Entwickler an, dass fehlende Dokumentation das größte Problem bei der Arbeit mit APIs darstellt. Fehlende Dokumentation verzögert die Entwicklung, erschwert das Onboarding neuer Entwickler und macht die Software weniger zuverlässig.
Wenn du deinen eigenen internen API-Katalog erstellen müsstest, wäre das ein gewaltiges Projekt mit vielen beweglichen Teilen. Diese ganze Arbeit übernehmen wir für dich – dein zentraler Dokumentations-Hub ist nur wenige Minuten entfernt.
Gib deinem Team die Informationen, die es braucht, und schau zu, wie es schneller ausliefert 🚀.