Mit API Management wachsen
– Ihr Weg, gut dokumentiert mit DocuPI

von Nicole Wesemeyer

Kunden über alle Kanäle und an allen digitalen Touchpoints zu begeistern ist heutzutage nicht mehr optional, sondern ein unverzichtbares Must-have.

Mit der zunehmenden Digitalisierung werden die Programmierschnittstellen, sogenannte Application Programming Interfaces (APIs), immer wichtiger, um die virtuelle und die physische Welt zu verschmelzen. Denn APIs bieten einen Zugang zu den Daten eines Unternehmens und machen sie für Kunden-, Mitarbeiter- und Partnerinteraktionen verfügbar. Laut einer Studie von Coleman Parks Research nutzen 2016 bereits 88% der großen globalen Firmen APIs. Im Schnitt konnten sie so ihre IT-Kosten um 41% senken und ihre Markteinführung beschleunigen [1].

Um richtig genutzt zu werden, benötigen APIs eine detaillierte Dokumentation, ein erhöhtes Maß an Sicherheit, umfassende Tests, routinemäßige Versionierung und hohe Zuverlässigkeit. Folglich ist ein effektives API Management von großer Bedeutung, damit Entwickler und Unternehmen APIs darüber sichern, steuern, skalieren, analysieren und natürlich auch monetisieren können. Je nach Größe des Unternehmens und dem Einsatz von APIs, kann das API Management viele weitere Aufgaben und Komplexitäten beinhalten.

Obwohl das Thema vorrangig aus Entwicklersicht behandelt wird, ist es für Unternehmen umso wichtiger, API Management aus der Business Perspektive zu treiben. Gutes API Management benötigt eine effiziente Organisation mit entsprechenden Ressourcen sowie ein API Portal, auch Developer Portal genannt.

Hierfür gibt es viele Anbieter, die zusätzlich zu ihren Gateways, komplette Portale mit eigenem Content Management Systemen (CMS), Foren und Ähnlichem betreiben. Wenn man einmal die verschiedenen Angebote näher betrachtet, stellt man schnell fest, dass ihre Vielfalt bezüglich des Inhaltes, Aufbaus und Designs vergleichbar ist mit dem Gefieder von Papageien. Die einen ähneln einander und die nächsten könnten kaum unterschiedlicher sein.

Viele Unternehmen die neu in die API Welt eintauchen, möchten sich mit der API Thematik vertraut machen und dann schrittweise hineinwachsen. Ein Developer Portal, in der Fülle und Mächtigkeit an Features der großen und bekannten Lösungsanbieter, kann hier überwältigend sein. Oft ist der eigene Tech-Stack auch nicht kompatibel mit dem des Lösungsanbieters, wie bspw. das CMS, welches zu zusätzlichen Ressourcen bzgl. der Einführung und Wartung führen würde. Neben den Fragen wie man mit APIs umgehen möchte und welche Standards erfüllt sein sollten, müssen auch erst einmal grundsätzliche Aufgabenstellungen wie Einrichtung, Maintenance, API Marketing beantwortet werden.

So wird aus einer technischen Weiterentwicklung ein komplexes Projekt und wächst einem schneller über den Kopf als man selbst in das Thema hineinwächst.

Um die Komplexität so gering wie möglich zu halten, ist es sinnvoll mit einem anpassungsfähigen API Dokumentationsportal zu beginnen. So kann man mit der Lösung wachsen und sich intern entsprechend besser organisieren.

So erging es auch einem unserer Kunden, den wir auf dem Weg zum API-Denken von Anfang an begleiten durften. Business Analysen und ausführliche Besprechungen ergaben, dass ein API Portal im Moment zu mächtig wäre und eigentlich mehr Arbeit als Nutzen erzeugen würde. Es fehlten interne Ressourcen für die Verwaltung. Außerdem war das Marketing von APIs gerade für externe Zwecke noch ein weit entferntes Zukunfts- und Sicherheitsthema.

Wir benötigten daher eine leichtgewichtige Version eines API Portals, d.h. eine abgespeckte Version, die auf das Wesentliche reduziert ist. Und zwar: eine interne Übersicht für APIs und deren Dokumentationen, die ohne Entwickler verwaltet werden können. Sowie ein Dokumentationsportal, mit der Möglichkeit zwischen fachlicher und technischer Dokumentation einer API zu unterscheiden, und damit die Lücke schließt, bis ein größeres API Portal wirklich betrieben werden kann.

Nachdem wir einige API Portale miteinander verglichen und analysiert hatten, haben wir darauf basierend verschiedene Konzepte und schließlich auch ein Prototyp erstellt, der unsere Funktionen und Ansprüche erfüllte. Eine kontinuierliche Rücksprache mit unserem Kunden war dabei ständig gegeben.

Dabei wurde uns schnell klar, dass für solch ein Dokumentationsportal die White Label Lösung DocuPI optimal ist. Es ermöglicht eine schnelle Anpassung der Inhalte ohne Entwickler oder direkt automatisiert über die Pipeline.

Wir erhofften uns damit auch, dass fachliche Dokumentationen hauptsächlich vom Product Owner – basierend auf einfachen Vorlagen – erstellt werden können. Die technische Dokumentation sollte sich in dem Swagger-File der API widerspiegeln. Zugleich sollte der gesamte Inhalt einfach und ohne Releases verwaltet werden können.

Unsere Whitelabel Lösung DocuPI

Key Features von DocuPI:

• ein reines Dokumentationsportal für APIs
• Whitelabel Lösung
• Trennen von fachlicher und technischer Dokumentation und damit neue, aber leichter umsetzbare Standards
• Basiert auf Markdown Dateien, die ohne Programmierkenntnisse genutzt werden können, z.B. für Textanpassungen oder auch neue Seiten und Änderungen einzuspeisen. Jedoch können diese jederzeit durch den Einsatz von HTML individualisiert und verfeinert werden
• Semi-automatisiert/ Container-basiert: Änderungen in der Markdown Datei werden ohne Deployment sichtbar. Dies ist besonders bei Dokumentationen von Vorteil.
• Zentrale Anlaufstelle für API Management:
  • Besseren Überblick über existierende APIs und die geplanten Entwicklungen
  • Handhabung interner Standards und Vorgaben wie REST Guidelines, Onboarding Prozesse
  • Kontakt & Unterstützung für die API-Entwicklung und Nutzung

Hier gibt es ein kurzes Video, um ein besseres Verständnis für das Aussehen und die Funktionsweise des Tools zu vermitteln: 

Mit dem Laden des Videos akzeptieren Sie die Datenschutzerklärung von YouTube.
Mehr erfahren

Video laden

YouTube immer entsperren

Vollständig an das eigene CI anpassbar, kann es bei jedem Unternehmen eingesetzt werden!

Unser Fazit:

Das Doku Portal hat die technische und fachliche Lücke erfolgreich und hervorragend geschlossen. Es ermöglicht unserem Kunden mit dem Thema API Management zu wachsen, sich mit der Struktur vertraut zu machen, einen API Überblick zu wahren und in Ruhe vorzubereiten, welche zusätzlichen Anforderungen für ein umfangreicheres, zukünftiges API Portal wichtig wären.

---

[1] Coleman Parks (2016), “Why digital transformation matters”

.