Developer Experience

API-Design - darauf kommt es an

25.08.2021
Von 


David Freund ist Managing Consultant beim IT-Dienstleister Senacor Technologies. Der Wirtschaftsinformatiker hat sich auf IT-Architekturen und Designmethoden spezialisiert.
Ob Open Banking, Cloud oder das Internet der Dinge: Unternehmen öffnen ihre IT nach außen. Meistens geschieht das über APIs, doch dabei kann einiges schiefgehen. Viele APIs sind nicht besonders entwicklerfreundlich.
  • Technische Fehler bei APIs führen zu schlechten Antwortzeiten. Und die sind geschäftsschädigend.
  • Wenn mit APIs die interne Fachlichkeit abgebildet wird, ist keine Akzeptanz zu erwarten.
  • Entwickler sind die Zielgruppe, weshalb Developer Experience zu einem zentralen Thema wird.
Schnittstellendesign ist kein Kinderspiel. Lesen Sie, wie Sie eine gute Developer Experience schaffen.
Schnittstellendesign ist kein Kinderspiel. Lesen Sie, wie Sie eine gute Developer Experience schaffen.
Foto: NDAB Creativity - shutterstock.com

Google hat herausgefunden, dass immerhin 38 Prozent seiner Cloud-Kunden einer "API-first"-Philosophie folgen. Sie stellen Schnittstellen auf einer Plattform bereit und erlauben eigenen Mitarbeitern wie auch externen Partnern darauf zuzugreifen. Die meisten tun das, weil sie ein besseres digitales Erlebnis für ihre Kunden schaffen und ihre Assets teilen oder zu Geld machen wollen. Jede zweite API lässt sich heute bereits von extern ansteuern, so der Bericht "State of API Economy 2021". Was die Kunden erfreuen dürfte, stellt allerdings für die Entwickler, die damit arbeiten müssen, allzu oft ein Ärgernis dar.

Viele APIs ignorieren etablierte Standards, etwa die der Berlin Group, oder setzen internes Wissen über IT-Systeme der anbietenden Unternehmen voraus. Ampelfarben kommen zum Einsatz, um zu beschreiben, ob bei einem Prozess alles glattläuft oder ein Problem auftritt. Auch eine große deutsche Bank macht das so. Statt Rot, Gelb oder Grün überrascht deren API allerdings mit der Ansage "TrafficLightColor:1". Welche Farbe soll das sein, 1? Das wird nirgends erklärt. Viele Unternehmen wissen, dass sie besser beschreiben müssen, wie ihre APIs arbeiten. Laut einer Umfrage von SmartBear bewerten mehr als zwei Drittel die Qualität ihrer API-Dokumentation als bestenfalls durchschnittlich.

API-Strategie in Banken
API-Strategie in Banken
Foto: Senacor

Wenn API-Plattformen aktiv und gern genutzt werden sollen, muss sich das ändern. Die Unternehmen brauchen dann neben einer guten User Experience (UX) so etwas wie eine Developer Experience (DX), inklusive Verantwortlicher, die sich darum kümmern. Das ergibt sich auch aus der API-Umfrage. Die einfache Bedienbarkeit ist das wichtigste Argument, wenn es darum geht, sich für oder gegen eine API zu entscheiden. Auf den weiteren Plätzen folgen eine präzise und umfassende Dokumentation und - mit etwas Abstand - die Performance.

Sie interessieren sich für APIs? dann lesen Sie auch:

Der Teufel steckt im API-Detail

Allerdings kann keine noch so großartige Dokumentation eine schlecht designte API aufwerten. Der Teufel steckt fast immer in einem der drei folgenden Details:

  • Technik: Was die API selbst betrifft;

  • Architektur: Wie die API aufgebaut ist;

  • Organisation: Wer sich (nicht) um die API kümmert.

Wer eine API entwickelt, sollte sich immer fragen: Was erwarten diejenigen, die später damit arbeiten sollen? Das gilt vor allem für die Entwickler, die diese Schnittstellen anbinden. Für sie muss es schnell und ohne unnötige Hürden gehen, damit sie ihre Projekte fertigstellen können. Bei der Technik lässt sich einiges falsch machen, was vor allem zu langen Reaktionszeiten führt. Diese betragen mitunter mehrere Sekunden. Solche APIs frustrieren und erweisen sich sogar als geschäftsschädigend, wenn beispielsweise Vergleichsportale zu langsame Tarifrechner nicht mehr einbinden. Wer Kfz-Versicherungen verkaufen will, dürfte hier gleich mal einen wichtigen Vertriebskanal verlieren.

Besonders ärgerlich ist es, wenn die API nicht mitteilt, dass es zu Verzögerungen kommt. Darunter leiden interne Nutzer genauso wie externe. Wer ständig mit einem Tarifrechner arbeiten muss, um Angebote zu schreiben oder Zahlungspläne für einen Kredit zu erstellen, wird lange Antwortzeiten nicht akzeptieren.

Viele APIs geben keinen Status

Häufig ist auch unklar, ob vom Nutzer oder dem System, das eine API nutzt, noch irgendeine Handlung erwartet wird. Viele APIs geben keinen detaillierten Status zurück und verraten auch nicht, wie es im Ablauf weitergeht. Das führt zu Ärger und abgebrochenen Vorgängen. Die Meldung "Vielen Dank, wir haben Ihre Bestellung erhalten und melden uns schon bald per E-Mail" gehört in Online-Shops längst zum guten Ton. Viele APIs verzichten aber darauf. Sie zwingen Nutzer und Systeme dazu, ständig nachzufragen (Polling) anstatt selbst Bescheid zu geben (Callback).

Was eine technisch gut gemachte API auszeichnet
Was eine technisch gut gemachte API auszeichnet
Foto: Senacor

Das fehlende Feedback kann sich negativ auf Geschäftspartner auswirken. Bestellte Ware soll beispielsweise erst dann versandt werden, wenn das Geld überwiesen wurde. Dafür muss bei vielen Zahlungsdienstleistern immer wieder nachgefragt werden, ob ein bestimmter Umsatz vorliegt, anstatt dass diese per Callback Bescheid geben, wenn die Zahlung unterwegs ist.

Darüber hinaus erlauben die häufig vorkommenden statischen Sandboxes Entwicklern oft nur einfache Integrationstests, um zu prüfen, ob sie die API technisch korrekt implementiert haben. Die fachlichen Tests erfolgen dann in Produktion mit Kleinstbeträgen und privaten Accounts. Automatisiertes Testen, der heutige Standard in der Softwareentwicklung, ist damit nicht möglich. Hierfür werden dynamische Testumgebungen benötigt, die Konsumenten erlauben, selber Daten anzulegen und diese analog der Produktion auch zu verarbeiten.

Komfortable API-Architekturen bauen

Fehler werden oft auch bei der Architektur einer API gemacht. Unternehmen bilden beispielsweise über ihre APIs die interne Fachlichkeit ab und erwarten von denjenigen, die mit der Schnittstelle arbeiten, dass ihnen diese fachliche Sicht bekannt ist. Nicht wenige Betriebe schicken ihre API-Nutzer sprichwörtlich von Pontius zu Pilatus.

Beispiel: Eine Bank möchte, dass die API-Anwender zuerst die Verträge und Vollmachten eines Kunden laden und anschließend zu jedem Vertrag die Produkte - etwa das Girokonto, Wertpapierdepot oder die Kreditkarte - aus den entsprechenden Services. Dabei kommen leicht fünf oder mehr Aufrufe zusammen, nur um zu erfahren, über welche Produkte ein Bankkunde verfügt. Die API bildet nur den Bestandsprozess ab. Das mag für vorhandene interne Prozesse noch gehen, für eine externe API sollte dagegen ein Abstraktions-Layer die interne Komplexität vor der Außenwelt verstecken, um den Aufruf zu vereinfachen.

Ähnliches gilt für interne Datenmodelle. Statt Standards wie die der Berlin Group zu nutzen, kommen manche APIs mit unverständlichen Ausdrücken daher, wie einem für nachfolgende Prozesse unabdingbarem Kanalkennzeichen, obwohl das für die API immer konstant bleibt. In Silostrukturen, wie sie in Banken, aber auch Versicherungen und größeren Organisationen häufig noch vorherrschen, entstehen zudem unterschiedliche Domänenmodelle, die ungefiltert in die APIs gelangen. Oft führt das dazu, dass ein und dasselbe Geschäftsobjekt unterschiedlich heißt. Ein Konto nennt sich beispielsweise mal Account, mal CashAccount, mal CurrentAccount und ein Kunde mal Person, mal Customer und mal Client. Idealerweise müssen die Anwender aber nur die API verstehen und nicht die Datenmodelle. Das gilt auch für die Geschäftsprozesse und die zugehörigen Funktionen.

Schema für eine REST-API, die ein Restaurant abbildet
Schema für eine REST-API, die ein Restaurant abbildet
Foto: Senacor

REST-APIs folgen genau diesem Prinzip. Sie übergeben ausschließlich Geschäftsobjekte und rudimentäre Anweisungen basierend auf dem HTTP-Protokoll, um Objekte abzurufen, zu speichern, zu ändern oder zu löschen. Wie die Abläufe hinter den APIs aussehen, wie also beispielsweise in einer Bank ein Konto angelegt wird, muss der Konsument nicht wissen. Typische Erfolgs- und Fehlermeldungen sehen auch immer gleich aus. 200 steht beispielsweise für OK, 403 für verboten - etwa, wenn Berechtigungen fehlen - und 404 für ein unbekanntes Geschäftsobjekt. Die meisten von uns kennen die 404-Meldung aus unserem Anwenderalltag. Browser geben diese Information zurück, wenn sie eine nicht oder nicht mehr existierende Webseite aufrufen wollen.

Solch eindeutigen Fehlercodes sind besonders wichtig für Anbieter, die fremde Dienste in ihre eigenen einbauen wollen, etwa beim Open Banking. Bleiben solche Rückmeldungen jedoch aus, können die Drittanbieter ihre eigenen Kunden nicht mehr richtig führen. Das ist ein Problem, weil die Kunden davon ausgehen, dass nicht die Bank - etwa bei einer Online-Bestellung - Mist gebaut hat, sondern der Shop-Betreiber.

Damit das nicht passiert, sollten sich Anbieter auch hier an Standards orientieren. Beispielsweise ist das gängige Problem, einen Kunden zu identifizieren, längst durch oAuth gelöst. Dieses Protokoll erlaubt, sich mit bereits validierten Daten eines Zweiten bei einem Dritten zu authentifizieren. "Login mit Facebook" heißt die damit umgesetzte Funktion beispielsweise in einigen Webshops. Auch hier müssen weder Banken noch andere Unternehmen das Rad neu erfinden.

Der Entwickler als Kunde und Ansprechpartner

Tolle APIs allein reichen noch nicht aus, um das Interesse von Entwicklern zu wecken. Doch genau darauf kommt es an, wenn das eigene Geschäftsmodell vorsieht, dass andere Unternehmen die angebotenen APIs für sich nutzen. Vom Open Banking bis zum Internet der Dinge - eine der drängenden Fragen lautet, wie sich die Schnittstellen zu Geld machen lassen. Klar ist: Ohne Entwickler geht gar nichts. Sie bilden neben End- und Firmenkunden künftig eine eigene Zielgruppe, um die sich Unternehmen kümmern müssen. Dazu gehört auch ein passender Kundendienst - ein Developer Service, wenn man so will. Dessen Service sollte über ein Entwicklerportal und eine FAQ hinausgehen. Auch Entwickler schätzen den persönlichen Kontakt.

Wie sinnvolle API-Architekturen bei der Usability helfen
Wie sinnvolle API-Architekturen bei der Usability helfen
Foto: Senacor

In der derzeit gelebten Praxis ist oft unklar, wer sich für APIs verantwortlich fühlt. In den Fachbereichen - im Banking etwa die für Konten, Karten und Wertpapiere - kümmern sich Spezialisten vereinzelt auch um die API. Doch deren Service Levels sind in der Regel nicht einheitlich geregelt. Mit anderen Worten: Viele APIs verdecken nur mühsam die Silos, die seit Jahrzehnten gewachsen sind.

Das führt zu qualitativen Unterschieden, was Antworten auf mögliche Rückfragen angeht. Einige Abteilungen antworten schneller als andere, manche verweisen stumpf auf die API-Spezifikationen, nur selten kümmert sich jemand wirklich um ein Anliegen. Viele Kontaktformulare drücken auf diese Weise eine Mentalität aus, die sich mit "Don't call us, we call you" umschreiben lässt. Das wird viele potenziell Interessierte abschrecken.

Das gilt auch für eine der wichtigsten Informationen über eine API: den Preis. Wer eine API nutzen will, schaut natürlich darauf: Fallen einmalige Kosten an? Wird monatlich oder volumenabhängig abgerechnet? Und wie läuft das Onboarding, wenn die App oder Software, in der die API später integriert ist, fertig ist und veröffentlicht werden soll? Zumindest eine erste Orientierung zu geben, hilft den Nutzern abzuschätzen, worauf sie sich einlassen. Das senkt die Einstiegshürde. Je einfacher sich eine API nutzen lässt, desto besser.

Es geht um Benutzerfreundlichkeit

Ease of Use ist im API-Zeitalter das maßgebliche Differenzierungsmerkmal. Wer die Wahl hat, welche Bank oder Versicherung als erstes integriert wird, entscheidet sich wahrscheinlich für jenen Anbieter, bei dem diese Arbeit leicht von der Hand geht. Die Unternehmen dürfen auf keinen Fall unterschätzen, wie wichtig dieser Aspekt wird, zumal Apps und Software, die eine API nutzen, die Reichweite für eigene Angebote erhöht.

Koch und Kellner sollten nicht verwechselt werden. Dankbar sein muss nicht nur der, der ein gutes Angebot für die eigenen Nutzer integrieren kann, sondern auch der, dessen Angebot integriert wird. Steht ein Nutzer vor der Frage, ob er eher die Bank oder die liebgewonnene App wechseln würde, dürfte in vielen Fällen die Bank leer ausgehen. Anwender zeigen heute Loyalität aufgrund von Convenience, weniger aufgrund eines Produkts.

Auf dem richtigen Weg ist, wer APIs als vollwertiges Produkt begreift, das die entsprechende Aufmerksamkeit genießen sollte. API as a Product bedeutet, einen Produktmanager mit einem Team einzustellen und die API zu behandeln wie einen weiteren Online-Kanal. Auch dort gibt es so etwas wie einen Second Level Process, um das Produkt aus der technischen Anonymität herauszuholen und mit richtigen Menschen darüber zu sprechen, falls es ein Problem gibt. Im agilen Methodenbaukasten finden die Unternehmen dafür auch die richtigen Werkzeuge, um ihre Fachbereiche einzubinden - Stichwort: API-Gilde. So gelingt es auch, neben einer guten Technik und einer sauberen API-Architektur für eine gute Developer Experience zu sorgen.