Entwerfen von Web APIs

Kapitel 1. Was ist eine API?

Diese Arbeit wurde mithilfe von KI übersetzt. Wir freuen uns über dein Feedback und deine Kommentare: [e-mail]

"Was ist eine API?" Wenn ein neuer Programmierer diese Frage stellt, bekommt er in der Regel die Antwort "eine Anwendungsprogrammierschnittstelle".

Aber APIs sind so viel mehr, als ihr Name vermuten lässt - und um ihren Wert zu verstehen und freizusetzen, müssen wir uns auf das Stichwort Schnittstelle konzentrieren.

Eine API ist die Schnittstelle, die ein Softwareprogramm anderen Programmen, Menschen und - im Fall von Web-APIs - der Welt über das Internet präsentiert. Das Design einer API verrät viel über das Programm, das dahinter steckt - das Geschäftsmodell, die Produktmerkmale und gelegentlich auch Fehler. Obwohl APIs für die Zusammenarbeit mit anderen Programmen entwickelt wurden, sind sie vor allem dafür gedacht, von den Menschen, die diese anderen Programme schreiben, verstanden und genutzt zu werden.

APIs sind die Bausteine, die die Interoperabilität der wichtigsten Geschäftsplattformen im Internet ermöglichen. Über APIs wird die Identität von Cloud-Softwarekonten erstellt und aufrechterhalten, von der E-Mail-Adresse deines Unternehmens über deine Software für kollaboratives Design bis hin zu den Webanwendungen, mit denen du deine Pizza bestellst. Über APIs werden Wettervorhersagedaten von einer seriösen Quelle wie dem Nationalen Wetterdienst an Hunderte von Softwareanwendungen weitergegeben, die sich auf deren Darstellung spezialisiert haben. APIs verarbeiten deine Kreditkarten und ermöglichen es Unternehmen, dein Geld nahtlos einzuziehen, ohne sich um die Feinheiten der Finanztechnologie und die entsprechenden Gesetze und Vorschriften kümmern zu müssen.

APIs werden immer mehr zu einer Schlüsselkomponente skalierbarer und erfolgreicher Internetunternehmen wie Amazon, Stripe, Google und Facebook. Für Unternehmen, die eine Geschäftsplattform schaffen wollen, die den Markt für alle erweitert, sind APIs ein wichtiger Teil des Puzzles.

Die Entwicklung deiner ersten API ist nur der Anfang. Dieses Buch geht über die Designprinzipien für deine erste API hinaus und zeigt dir, wie du eine API zusammen mit deinem Unternehmen entwickeln und ausbauen kannst. Wenn du die richtigen Entscheidungen triffst, wird deine API den Test der Zeit bestehen.

Warum brauchen wir APIs?

APIs sind aus dem Bedürfnis heraus entstanden, Informationen mit Datenanbietern auszutauschen, die in der Lage sind, bestimmte Probleme zu lösen, damit die Leute in anderen Unternehmen nicht selbst Zeit damit verbringen müssen, diese Probleme zu lösen. Du möchtest zum Beispiel eine interaktive Karte in eine Webseite einbinden, ohne Google Maps neu zu erfinden. Vielleicht willst du einen Benutzer anmelden, ohne den Facebook-Login neu zu erfinden. Oder du möchtest einen Chatbot erstellen, der gelegentlich mit Nutzern interagiert, ohne dass du ein Echtzeit-Nachrichtensystem entwickeln musst.

In all diesen Fällen werden zusätzliche Funktionen und Produkte mithilfe von Daten oder Interaktionen von einer speziellen Plattform erstellt. APIs ermöglichen es Unternehmen, schnell einzigartige Produkte zu entwickeln. Anstatt das Rad neu zu erfinden, können Start-ups ihr Produktangebot differenzieren, indem sie die Vorteile bestehender Technologien nutzen und andere Ökosysteme anzapfen.

Wer sind unsere Nutzer?

Die ganze Theorie ist unwichtig, wenn du dich nicht darauf konzentrierst, das Richtige für den richtigen Kunden zu bauen.

Bilal Aijazi, CTO bei Polly

Wenn du ein Produkt entwickelst, ist es eine gute Idee, dich zuerst auf den Kunden zu konzentrieren. Das ist auch bei der Entwicklung einer API sehr wichtig. In Kapitel 8 sprechen wir über verschiedene Arten von Entwicklern und Anwendungsfällen sowie über Strategien, um mit ihnen in Kontakt zu treten und ihnen einen Mehrwert zu bieten. Es ist wichtig, dass du verstehst, wer deine Entwickler sind, was ihre Bedürfnisse sind und warum sie deine API nutzen. Wenn du dich auf die Entwickler/innen konzentrierst, verhinderst du, dass du APIs baust, die niemand nutzen will oder die nicht zu den Nutzungsanforderungen deiner Entwickler/innen passen.

Da es sehr schwierig ist, das Design einer API im Nachhinein zu ändern, ist es wichtig, dass du deine API spezifizierst und validierst, lange bevor du mit ihrer Implementierung beginnst. Die Kosten für den Wechsel von einem API-Design zum anderen sind für die meisten Entwickler extrem hoch.

Hier sind einige Beispiele für Anwendungsfälle für eine API zum Hochladen und Speichern von Bildern:

• Lisa ist Webentwicklerin in einem Startup, das Kunst verkauft, und sie braucht eine einfache Möglichkeit für die Künstler, Fotos von ihren Arbeiten hochzuladen und zu zeigen.

• Ben ist ein Backend-Unternehmensentwickler, der Belege aus dem Spesensystem in seiner Prüfungs- und Richtlinienlösung speichern muss.

• Jane ist eine Frontend-Entwicklerin, die einen Echtzeit-Kundensupport-Chat in die Website ihres Unternehmens integrieren möchte.

Das sind nur ein paar Beispiele, die alle ihre eigenen versteckten Anforderungen und Bedürfnisse haben. Wenn du die Bedürfnisse deiner Entwickler/innen nicht berücksichtigst, wird deine API nicht erfolgreich sein.

Im nächsten Abschnitt sprechen wir über übergeordnete Anwendungsfälle, die sich auf das Design deiner API auswirken können, aber je detaillierter du deine Anwendungsfälle beschreiben kannst und je besser du deine Entwickler verstehst, desto besser kannst du sie bedienen.

Der Business Case für APIs

Es ist kein Geheimnis, dass ein großer Teil der Produktinnovationen und des Technologiemarktes heute vom Internet bestimmt wird. Daher sind APIs wichtiger denn je, wenn es darum geht, ein Unternehmen zu gründen, und es gibt viele Modelle, um sie in ein Produkt einzubauen. In einigen Fällen führt eine API zu direktem Gewinn und Monetarisierung (über Gewinnbeteiligungsmodelle, Abonnementgebühren oder Nutzungsgebühren). Es gibt aber auch viele andere Gründe, warum du eine API erstellen möchtest. APIs können die allgemeine Produktstrategie deines Unternehmens unterstützen. Sie können ein wichtiges Puzzlestück für die Integration von Diensten Dritter in das Produkt deines Unternehmens sein. APIs können Teil einer Strategie sein, die andere dazu anregt, zusätzliche Produkte zu entwickeln, in die der Entwickler des Hauptprodukts nicht investieren will oder kann. APIs können auch ein Weg sein, um neue Kunden zu gewinnen, neue Vertriebskanäle für ein Produkt zu erschließen oder Upselling-Produkte anzubieten. Weitere Informationen zu diesen Strategien findest du in der Präsentation von John Musser über API-Geschäftsmodelle.

Eine API muss auf das Kerngeschäft abgestimmt sein, wie es bei vielen Software-as-a-Service-Unternehmen (SaaS) der Fall ist. Bekannte Beispiele sind GitHub, Salesforce und Stripe. Manchmal werden die Produkte, die auf diesen APIs aufbauen, auch als "Service-Integrationen" bezeichnet. Verbraucher-APIs funktionieren gut, wenn es eine kritische Masse an nutzergenerierten Inhalten gibt, wie z. B. bei den Foto-Sharing-Funktionen von Facebook und Flickr. Obwohl es viele Gründe gibt, eine API zu erstellen und eine Entwicklerplattform zu starten, gibt es auch einen klaren Grund, keine Entwicklerplattform zu erstellen - nämlich dann, wenn die API-Strategie nicht auf das Kerngeschäft abgestimmt ist. Wenn beispielsweise die Haupteinnahmequelle des Produkts die Werbung ist, führen APIs, die alternative "Clients" für das Produkt ermöglichen, dazu, dass der Verkehr von dem Erlebnis, in dem die Werbung gehostet wird, weggeht. Dadurch wird die Umsatzbeteiligung geschmälert, wie es bei der Twitter-API der Fall war.

Abgesehen von der Monetarisierung und den geschäftlichen Anreizen wollen wir uns die folgenden Möglichkeiten genauer ansehen, mit denen einige Unternehmen ihre API-Entwicklung strukturiert haben:

• APIs zuerst für interne Entwickler, dann für externe Entwickler

• APIs zuerst für externe Entwickler, dann für interne Entwickler

• APIs als das Produkt

APIs für interne Entwickler zuerst, externe Entwickler an zweiter Stelle

Manche Unternehmen entwickeln ihre APIs zuerst für interne Entwickler und geben sie dann für externe Entwickler frei. Dafür kann es eine Reihe von Beweggründen geben. Ein Grund könnte sein, dass das Unternehmen einen potenziellen Wert darin sieht, eine externe API hinzuzufügen. Dies könnte ein Entwickler-Ökosystem schaffen, die Nachfrage nach dem Produkt des Unternehmens steigern oder es anderen Unternehmen ermöglichen, Produkte zu entwickeln, die das Unternehmen selbst nicht entwickeln möchte.

Schauen wir uns einmal an, wie die API von Slack entstanden ist - als API für die Web-, Desktop- und Mobil-Clients von Slack, um eine Messaging-Oberfläche anzuzeigen. Obwohl Slack seine APIs ursprünglich für seine internen Entwickler/innen entwickelt hat, geschah etwas anderes, als das Unternehmen wuchs: Eine Handvoll "Integrationen" mit wichtiger Unternehmenssoftware wurde zu einem wichtigen Puzzlestück für das Wachstum und die Entwicklung von Slack als Kommunikationssoftware. Anstatt maßgeschneiderte Apps zu entwickeln, um sein Angebot in andere Unternehmen zu integrieren, führte Slack seine Entwicklerplattform und eine Reihe von Produkten für Drittentwickler ein, mit denen sie ihre eigenen Apps entwickeln können, sowohl bei etablierten Unternehmen als auch bei neuen Start-ups.

Dieser Schritt von Slack trug dazu bei, das Ökosystem für Apps zu erweitern, die sich in die Messaging-Plattform von Slack integrieren. Es bedeutete auch, dass Slack-Nutzer/innen, die auch andere Unternehmenssoftware nutzen, nahtlos dort zusammenarbeiten konnten, wo die Kommunikation bereits im Slack-Messaging-Client stattfand.

Der Vorteil der Slack-APIs zum Zeitpunkt der Einführung der Entwicklerplattform war, dass die APIs bereits getestet waren und von internen Entwicklern gut genutzt wurden. Die Nachteile dieses Ansatzes zeigten sich im Laufe der Zeit, als sich die Bedürfnisse der externen Entwickler von den Bedürfnissen der internen Entwickler entfernten. Interne Entwickler brauchten Flexibilität, um neue Erfahrungen für die Endnutzer des Messaging-Clients zu schaffen, von neuen Arten von gemeinsamen Kanälen, Dateien und Nachrichten bis hin zu anderen, immer komplexeren Kommunikationserfahrungen. In der Zwischenzeit erstellten Drittentwickler keine Ersatz-Client-Benutzeroberflächen (UIs) mehr für Slack - sie begannen, leistungsstarke Geschäftsanwendungen und Tools zu entwickeln, die eher auf Workflows als auf die Anzeige von Nachrichten ausgerichtet waren. Externe Entwickler brauchten auch Stabilität, und das Spannungsverhältnis zwischen der Abwärtskompatibilität der API und der Notwendigkeit, die API für neue Produktfunktionen zu ändern, ging zu Lasten der Projektgeschwindigkeit in Slack.

APIs für externe Entwickler zuerst, interne Entwickler an zweiter Stelle

Manche Unternehmen erstellen zuerst APIs für externe Interessengruppen und geben sie dann für interne Interessengruppen frei. So ist GitHub von Anfang an vorgegangen. Werfen wir einen Blick darauf, wie und warum GitHub seine API entwickelt hat und wie sein Entwicklerpublikum die Entwicklung der API beeinflusst hat.

Zu Beginn richtete sich die API von GitHub vor allem an externe Entwickler, die einen programmatischen Zugang zu ihren eigenen Daten erhalten wollten. Kurz nach der ersten Veröffentlichung der API begannen sich kleine Unternehmen rund um die GitHub-API zu bilden. Diese Unternehmen entwickelten Entwickler-Tools und verkauften sie an die Nutzer von GitHub.

Seitdem hat GitHub sein API-Angebot erheblich erweitert. Es hat eine API entwickelt, die sowohl Einzelpersonen dient, die ihre eigenen Projekte oder Workflows erstellen wollen, als auch Teams, die zusammenarbeiten wollen, um Bot-Skripte oder Workflow-Tools zu entwickeln, die sich in GitHub integrieren lassen. Diese Teams, die so genannten Integratoren, erstellen Entwickler-Tools, verbinden Nutzer mit der GitHub-Plattform und verkaufen diese Tools an gemeinsame Kunden.

Als es für GitHub an der Zeit war, seine GraphQL-API zu entwickeln, waren Drittentwickler die ersten Kunden. GraphQL ist eine Abfrage-Schnittstelle für Web-APIs. Obwohl sie nicht die erste Schnittstelle dieser Art ist, hat sie vor dem Schreiben dieses Buches durch ihre Implementierung bei Facebook, einem bekannten API-Anbieter, und ihre Übernahme durch GitHub, einem anderen bekannten API-Anbieter, für Aufsehen gesorgt. Nachdem Entwickler von Drittanbietern begannen, die neue GraphQL-API von GitHub zu nutzen, setzten auch interne GitHub-Entwickler sie ein, um die GitHub-Web-UI und Client-Anwendungen zu betreiben.

Im Fall von GitHub war die API zunächst für externe Stakeholder gedacht und hat sich dann weiterentwickelt, um auch internen Entwicklern zu dienen. Ein Vorteil dieses Ansatzes ist, dass die API an externe Entwickler angepasst werden kann, anstatt zwei Zielgruppen zu überbrücken. Als sich die API von GitHub weiterentwickelte, konnten die JSON-Antworten mit immer mehr Daten versehen werden, die die Entwickler benötigten. Schließlich waren die Nutzdaten so umfangreich, dass GitHub GraphQL einführte, damit die Entwickler die gewünschten Felder in den Abfragen angeben konnten. Ein Nachteil dieses Ansatzes im Fall von GraphQL ist, dass aufgrund der Flexibilität, die GraphQL den Entwicklern bietet, auftretende Leistungsengpässe auf eine Vielzahl von Zugriffsmustern verteilt sind. Das kann die Fehlersuche erschweren, wenn man nur mit einem einzigen Endpunkt arbeitet, wie z. B. im Fall von REST.

Hinweis

Weitere Details zu GraphQL findest du in Kapitel 2.

APIs als das Produkt

Für einige Unternehmen ist die API das Produkt. Das ist bei Stripe und Twilio der Fall. Stripe bietet APIs für die Zahlungsabwicklung im Internet an. Twilio bietet APIs für die Kommunikation über SMS, Sprache und Messaging. Im Fall dieser beiden Unternehmen ist der Aufbau einer API zu 100 % auf ein Ein-Produkt-Publikum ausgerichtet. Die API ist das Produkt, und das gesamte Unternehmen ist darauf ausgerichtet, eine nahtlose Schnittstelle für die Kunden zu schaffen. Was die Verwaltung von APIs und die Erfüllung von Nutzerbedürfnissen angeht, ist die API als Produkt die einfachste Unternehmensform, die möglich ist.

Was macht eine API großartig?

Wir haben Branchenexperten diese Frage gestellt und die Antworten liefen darauf hinaus, ob die API das erreicht, was sie tun soll. Um die Aspekte zu ergründen, die zur Benutzerfreundlichkeit einer API beitragen, werden wir nicht nur Aspekte der Gestaltung und Skalierung von APIs untersuchen, sondern auch die Unterstützung und die Ökosysteme, die es Entwicklern ermöglichen, APIs zu nutzen.

Expertenrat

Eine gute API hängt von dem Problem ab, das du zu lösen versuchst, und davon, wie wertvoll es ist, es zu lösen. Du bist vielleicht bereit, eine verwirrende, inkonsistente und schlecht dokumentierte API zu nutzen, wenn du dadurch Zugang zu einem einzigartigen Datensatz oder einer komplexen Funktion erhältst. Ansonsten bieten gute APIs in der Regel Klarheit (in Bezug auf Zweck, Design und Kontext), Flexibilität (Anpassungsfähigkeit an verschiedene Anwendungsfälle), Leistungsfähigkeit (Vollständigkeit der angebotenen Lösung), Hackability (Fähigkeit, durch Iteration und Experimentieren schnell zu lernen) und Dokumentation.

Chris Messina, Leiter der Entwicklererfahrung bei Uber

Benutzerfreundlichkeit, Skalierbarkeit und Leistung sind einige der Aspekte, die eine gute API ausmachen. Wir behandeln viele dieser Themen in den Kapiteln 2 bis 4 dieses Buches. Auch die Dokumentation und die Ressourcen für Entwickler sind wichtig, damit die Nutzer erfolgreich arbeiten können. Wir behandeln diese Themen in den Kapiteln 7 bis 9. Da es unmöglich ist, eine API für alle Faktoren zu optimieren, muss das Implementierungsteam schwierige Entscheidungen darüber treffen, was für den Endnutzer am wichtigsten ist. In Kapitel 7 erfährst du, wie du eine Strategie entwickeln kannst, um dies zu erreichen.

Ein weiterer Punkt, den es zu bedenken gilt, ist die Frage, wie eine großartige API den Test der Zeit bestehen wird. Veränderungen sind schwierig und unvermeidlich. APIs sind flexible Plattformen, die Unternehmen miteinander verbinden, und die Geschwindigkeit des Wandels ist variabel. In großen Unternehmen ist die Veränderungsrate langsamer als in kleinen Start-ups, die noch nicht zum Produktmarkt gefunden haben. Aber manchmal bieten diese kleinen Startups über APIs unschätzbare Dienste an, die Unternehmen nutzen müssen. In Kapitel 5 erfährst du außerdem, wie du APIs so gestaltest, dass sie den Test der Zeit und der Veränderungen bestehen.

Schlussgedanken

Zusammenfassend lässt sich sagen, dass APIs ein wichtiger Bestandteil moderner Technologieprodukte sind und dass es viele Möglichkeiten gibt, ein Unternehmen mit ihnen zu strukturieren. In Kapitel 2 geben wir dir einen Überblick über API-Design-Paradigmen.