Kapitel 4. Die Säulen eines API-Produkts

Diese Arbeit wurde mithilfe von KI übersetzt. Wir freuen uns über dein Feedback und deine Kommentare: translation-feedback@oreilly.com

Wenn es gut gemacht ist, sieht es einfach aus. Die Leute haben keine Ahnung, wie kompliziert und schwierig es wirklich ist. Wenn du an einen Film denkst, stellen sich die meisten Leute ein zweistündiges, fertig poliertes Produkt vor. Aber um dieses zweistündige Produkt zu erreichen, können Hunderte oder Tausende von Menschen viele Monate Vollzeitarbeit leisten.

George Kennedy

Im vorigen Kapitel haben wir die API als ein Produkt betrachtet. Werfen wir nun einen Blick auf die Arbeit, die du leisten musst, um dein Produkt zu entwickeln und zu pflegen. Die Wahrheit ist, dass es eine Menge harter Arbeit erfordert, eine gute API zu entwickeln. In Kapitel 1 hast du gelernt, dass APIs aus drei verschiedenen Teilen bestehen: Schnittstellen, Implementierungen und Instanzen. Um deine API zu erstellen, musst du Zeit und Mühe in die Verwaltung aller drei Aspekte investieren. Darüber hinaus musst du alles auf dem neuesten Stand halten, da dein Produkt ständig reift und sich verändert. Um dir dabei zu helfen, diese ganze Komplexität zu verstehen und zu bewältigen, haben wir diese Arbeit in 10 Säulen unterteilt.

Wir nennen sie Säulen, weil sie dein API-Produkt unterstützen. Wenn du in keine der Säulen investierst, ist dein Produkt zum Fallen und Fehlschlagen verurteilt. Das heißt aber nicht, dass du in alle Säulen maximal investieren musst, um mit deiner API erfolgreich zu sein. In diesem Kapitel haben wir 10 Säulen identifiziert. Das Schöne an diesen 10 Säulen ist, dass sie nicht alle gleich viel Gewicht haben müssen. Einige Pfeiler können stärker sein als andere, und du kannst sogar entscheiden, dass einige Pfeiler gar nicht so viel Investition benötigen. Wichtig ist, dass die kombinierte Stärke dieser Säulen deine API erhöht, auch wenn sie sich im Laufe der Zeit weiterentwickelt und verändert.

Die Säulen stellen sich vor

Jede der API-Säulen bildet eine Grenze für einen Arbeitsbereich. Oder anders ausgedrückt: Jede Säule begrenzt eine Reihe von API-bezogenen Entscheidungen. In der Realität lässt sich dein Arbeitsaufwand nicht so genau kategorisieren, und einige der Säulen werden sich überschneiden. Aber das ist in Ordnung. Es geht uns nicht darum, eine unumstößliche Wahrheit über API-Arbeit zu definieren, sondern ein nützliches Modell zu entwickeln, mit dem wir die Arbeit, die mit der Erstellung von API-Produkten verbunden ist, untersuchen und darüber sprechen können. Wir werden im Laufe des Buches auf diesem grundlegenden Konzept der Säulen aufbauen, indem wir in den folgenden Kapiteln fortgeschrittenere Modelle für die Teamorganisation, die Produktreife und landschaftliche Aspekte entwickeln.

Die 10 Säulen, die wir für die API-Arbeit definiert haben, sind die folgenden:

Strategie
Entwurf
Dokumentation
Entwicklung
Testen
Einsatz
Sicherheit
Überwachung
Entdeckung
Veränderungsmanagement

In diesem Kapitel werden wir jede dieser Säulen vorstellen und untersuchen, was sie sind und warum sie für den Erfolg eines API-Produkts wichtig sind. Außerdem beschreiben wir den Entscheidungsspielraum für jede Säule und geben einige allgemeine Hinweise, wie man sie stärken kann. Wir werden dir in diesem Kapitel keine konkrete Anleitung geben, wie du eine der Säulen umsetzen kannst - schließlich könnte eine vollständige Erörterung jedes dieser Arbeitsbereiche ein ganzes Buch füllen, und wir haben noch viele weitere Konzepte für das API-Management zu behandeln. Wir werden jedoch einige der wichtigsten Entscheidungen in jedem Bereich aus der Governance-Perspektive herausstellen. Werfen wir zunächst einen Blick auf die erste Säule eines API-Produkts: die Strategie.

Strategie

Großartige Produkte beginnen mit einer großartigen Strategie, und bei API-Produkten ist das nicht anders. Die Säule der API-Strategie umfasst zwei wichtige Entscheidungsbereiche: warum du deine API bauen willst (das Ziel) und wie eine API dir helfen wird, dieses Ziel zu erreichen (die Taktik). Es ist wichtig zu verstehen, dass dein strategisches Ziel für die API nicht in einem Vakuum existieren kann. Welches Ziel du dir auch immer für dein API-Produkt ausdenkst, es muss für das Unternehmen, das es besitzt, einen Mehrwert darstellen. Das bedeutet natürlich, dass du zunächst eine Vorstellung von der Strategie oder dem Geschäftsmodell deines Unternehmens haben musst. Wenn du über die Ziele deines Unternehmens im Unklaren bist, solltest du das herausfinden, bevor du mit der Entwicklung neuer APIs beginnst.

Dein Geschäft mit APIs vorantreiben

Wie stark sich dein API-Produkt auf deine Unternehmensstrategie auswirkt, hängt stark vom Kontext deines Unternehmens ab. Wenn die Haupteinnahmequelle deines Unternehmens der Verkauf von API-Zugängen an Drittentwickler ist (z. B. die Kommunikations-APIs von Twilio oder die Zahlungs-API von Stripe), dann ist die Strategie deines API-Produkts eng mit deiner Unternehmensstrategie verknüpft. Wenn die API gut läuft, profitiert das Unternehmen, wenn sie nicht gut läuft, schlägt das Unternehmen fehl. Das API-Produkt wird zum wichtigsten Wertschöpfungskanal für dein Unternehmen, und seine Architektur und sein Geschäftsmodell werden implizit auf die Ziele des Unternehmens abgestimmt.

Die meisten Unternehmen haben jedoch bereits bestehende, "traditionelle" Geschäftsbereiche, die durch die APIs unterstützt werden sollen. In diesen Fällen wird eine API nicht die neue Haupteinnahmequelle werden, es sei denn, das Unternehmen ändert seine Strategie grundlegend. Eine Bank, die seit Hunderten von Jahren tätig ist, kann zum Beispiel eine API für externe Entwickler/innen öffnen, um eine "Open Banking"-Initiative zu unterstützen. Wenn man sich nur auf das Geschäftsmodell der API konzentriert, könnte das dazu führen, dass man ein Einnahmemodell für die API einführt, bei dem Entwickler/innen für den Zugang zu API-basierten Bankfunktionen bezahlen müssen. Aber wenn man das Gesamtbild der Bank betrachtet, wäre diese API-Strategie nachteilig, weil sie eine Nutzungsbarriere schafft. Stattdessen kann die Banking-API kostenlos (und mit Verlust) angeboten werden, in der Hoffnung, die digitale Reichweite der Bank zu erhöhen, was zu einer Steigerung des Absatzes der Kernbankprodukte führt.

Die API-Strategie gilt nicht nur für APIs, die nach außen angeboten werden, sondern ist auch ein wichtiger Pfeiler für deine internen APIs. Das bedeutet, dass du auch für sie eine Produktstrategie festlegen musst. Der einzige wirkliche Unterschied zwischen der internen API-Strategie und der externen API-Strategie liegt in den Nutzern, die sie bedienen. Bei beiden Arten von APIs geht es darum, zu verstehen, warum es die API geben muss und wie sie diese Bedürfnisse erfüllen kann. Unabhängig davon, in welchem Kontext deine API eingesetzt wird, lohnt es sich, ein strategisches Ziel für die API zu entwickeln, das deiner Organisation einen Nutzen bringt.

Sobald du ein strategisches Ziel für dein API-Produkt hast, musst du eine Reihe von Taktiken entwickeln, die dir helfen, es zu erreichen.

Taktiken definieren

Um ein strategisches API-Ziel zu erreichen, musst du einen Plan für dein Produkt erstellen, der dich dorthin führt. Du musst eine Reihe von Taktiken für deine Arbeit entwickeln, die dir die besten Erfolgschancen bieten. Im Wesentlichen leitet deine Strategie die gesamte entscheidungsbasierte Arbeit, die du in den anderen neun Säulen leisten wirst. Die Herausforderung besteht darin, die Verbindung zwischen den einzelnen Bereichen der Entscheidungsarbeit und deinem Ziel zu verstehen.

Schauen wir uns ein paar Beispiele an:

Ziel: Steigerung der geschäftsspezifischen Fähigkeiten deiner Plattform: Wenn du dich darauf konzentrierst, eine größere Anzahl von geschäftsorientierten APIs aufzubauen, solltest du deine Taktik dahingehend ändern, wie du deine API überhaupt erst konzipierst und erstellst. Zum Beispiel solltest du die Stakeholder deines Unternehmens bereits in der Entwurfsphase deiner API einbeziehen, um sicherzustellen, dass die richtigen Funktionen über deine Schnittstelle bereitgestellt werden. Wahrscheinlich wirst du dich auch an ihnen orientieren, wenn es darum geht, wer die Hauptnutzer sind und wo die Grenzen der API liegen sollten.
Ziel: Interne Vermögenswerte monetarisieren: Ein Monetarisierungsfokus erfordert eine Reihe von Taktiken, die dir helfen, dein Produkt einer Nutzergemeinschaft zugänglich zu machen, die es für wertvoll hält. Das bedeutet in der Regel auch, dass du dich in einem wettbewerbsintensiven Markt bewegst, sodass die Entwicklererfahrung (DX) bei der Nutzung deiner API sehr wichtig wird. In taktischer Hinsicht bedeutet das, dass du mehr in Design, Dokumentation und Entdeckung investieren musst. Das bedeutet auch, dass du Marktforschung betreiben musst, um die richtige Zielgruppe für deine API zu finden und sicherzustellen, dass du die richtige Art von Produkt für sie hast.
Ziel: Geschäftsideen sammeln: Wenn es dein Ziel ist, innovative Ideen von außerhalb deines Unternehmens zu finden, musst du eine Reihe von Taktiken entwickeln, die die Nutzung deiner API auf innovative Weise fördern. Das bedeutet, dass du die API nach außen hin vermarkten und sie so gestalten musst, dass sie für eine Nutzergemeinschaft attraktiv ist, die den größten potenziellen Innovationswert bietet. Es ist auch sinnvoll, stark in die Entdeckungssäule zu investieren, um sicherzustellen, dass du die Nutzung so weit wie möglich vorantreiben kannst, um so viele Ideen wie möglich zu sammeln. Außerdem brauchst du eine klare Taktik, um die besten Ideen zu identifizieren und sie weiterzuentwickeln.

Wie wir an diesen drei Beispielen sehen können, musst du Folgendes tun, um starke Taktiken für deine API zu entwickeln:

Finde heraus, welche Säulen für den Erfolg wichtig sind.
Finde heraus, welche Nutzergemeinschaften zum Erfolg beitragen werden.
Sammle kontextbezogene Daten, um deine Entscheidungsfindung zu unterstützen.

Anpassen deiner Strategie

Es ist zwar wichtig, dass du zu Beginn des Aufbaus deiner API eine gute Taktik entwickelst, aber es ist auch wichtig, dass deine Strategie fließend bleibt und sich ändern kann. Es ist nicht gut, wenn du dein strategisches Ziel und deinen taktischen Plan einmal festlegst und dann wieder weggehst. Stattdessen musst du deine Strategie anhand der Ergebnisse, die du mit deinem Produkt erzielst, anpassen. Wenn du keine Fortschritte machst, musst du deine Taktik ändern, vielleicht dein Ziel anpassen oder sogar die API aufgeben und neu beginnen.

Um deine strategischen Fortschritte zu dokumentieren, brauchst du eine Möglichkeit, deine API-Ergebnisse zu messen. Es ist sogar unerlässlich, dass du eine Reihe von Messgrößen für deine strategischen Ziele hast - sonst wirst du nie wissen, wie gut du bist. Wir werden in Kapitel 7 mehr über Ziele und Messungen für APIs sprechen, wenn wir OKRs und KPIs für APIs vorstellen. Die Messung hängt auch von der Möglichkeit ab, Daten über die API zu sammeln, daher musst du auch in die Überwachungssäule investieren.

Du solltest auch bereit sein, deine Strategie zu ändern, wenn sich der Kontext deiner API ändert: zum Beispiel, wenn deine Organisation ihr strategisches Ziel ändert, ein neuer Wettbewerber auf deinem Markt auftaucht oder die Regierung eine neue Art von Regulierung einführt. In jedem dieser Fälle kann eine schnelle Anpassung den Wert deiner API erheblich steigern. Strategische Veränderungen werden jedoch durch die Veränderbarkeit deiner API begrenzt, daher ist die Säule des Veränderungsmanagements (die weiter unten in diesem Kapitel behandelt wird) eine wichtige Investition.

Wichtige Entscheidungen für die strategische Steuerung

Was ist das Ziel und der taktische Plan der API?: Die Festlegung eines Ziels und eines Plans, um es zu erreichen, ist ein Kernstück der Strategiearbeit. Es ist wichtig, sorgfältig zu überlegen, wie diese Entscheidungsarbeit verteilt werden soll. Du kannst den einzelnen Teams erlauben, ihre eigenen Ziele und Taktiken zu definieren, um die Vorteile der lokalen Optimierung zu nutzen, oder du kannst die Zielplanung zentralisieren, um die Systemoptimierung zu verbessern. Wenn du dich dafür entscheidest, die API-Strategiearbeit zu dezentralisieren, musst du Anreize und Kontrollen schaffen, um zu verhindern, dass eine einzelne API irreparablen Schaden anrichtet. Zum Beispiel kann die Zentralisierung des Genehmigungsschritts einer Zielsetzungsentscheidung den Prozess verlangsamen, aber unerwartete Probleme verhindern.
Wie wird die strategische Wirkung gemessen?: Das Ziel der API ist eine lokale Definition, aber du musst auch festlegen, wie gut dieses Ziel mit den Interessen der Organisation übereinstimmt. Diese Messung kann dezentral erfolgen und den API-Teams überlassen werden, oder sie kann zentralisiert und standardisiert werden. Du kannst zum Beispiel einen einheitlichen Prozess mit standardisierten Kennzahlen einführen, den die Teams für API-Berichte befolgen müssen. Dies bietet dir den Vorteil einheitlicher Daten für die Analyse auf Systemebene.
Wann ändert sich die Strategie?: Manchmal müssen Ziele geändert werden, aber wer darf diese Entscheidung treffen? Das Problem bei der Änderung des Ziels einer API ist, dass sie in der Regel große Auswirkungen hat, sowohl auf die API selbst als auch auf die Menschen, die auf sie angewiesen sind. Auch wenn du deinen Teams die Freiheit gibst, das Ziel einer neuen API festzulegen, musst du mehr Kontrollen für Zieländerungen einführen, vor allem, wenn die API eine Phase der intensiven Nutzung erreicht hat.

Entwurf

Design Arbeit findet statt, wenn du Entscheidungen darüber triffst, wie etwas, das du kreierst, aussehen, sich anfühlen und benutzt werden soll. Alles, was du erschaffst oder veränderst, beinhaltet Designentscheidungen. Tatsächlich können alle Entscheidungen, die wir in den verschiedenen Abschnitten dieses Kapitels beschreiben, auch als Designarbeit betrachtet werden. Aber die Säule des API-Designs, die wir hier beschreiben, ist etwas Besonderes. Sie ist auf eine bestimmte Art von Entwurfsarbeit beschränkt: die Entscheidungen, die du triffst, wenn du die API-Schnittstelle entwirfst.

Wir haben das Oberflächendesign als eigene Säule herausgestellt, weil es einen so großen Einfluss auf deine API hat. Obwohl sie nur ein Teil einer API ist, ist die Schnittstelle alles, was deine Nutzer sehen, wenn sie dein Produkt nutzen wollen. Für sie ist die Schnittstelle die API. Deshalb hat das Design der Schnittstelle einen großen Einfluss auf die Entscheidungen, die du in den anderen Säulen triffst. Wenn du dich zum Beispiel dafür entscheidest, dass deine API eine ereignisbasierte Schnittstelle haben soll, ändert sich die Arbeit, die du für die Implementierung, Bereitstellung, Überwachung und Dokumentation leisten musst, radikal.

Du musst viele Entscheidungen treffen, wenn du deine Schnittstelle gestaltest. Hier sind einige der wichtigsten Dinge, die du beachten musst:

Vokabulare: Was sind die Wörter und Begriffe, die deine Nutzer verstehen müssen? Über welche Sonderzeichen müssen sie Bescheid wissen?
Styles: Welche Protokolle, Nachrichtenmuster und Schnittstellenstile wird die Schnittstelle verwenden? Wird deine API zum Beispiel das CRUD-Muster verwenden? Oder wird sie einen Ereignisstil verwenden? Oder so etwas wie den GraphQL-Abfragestil?
Interaktionen: Wie wird deine API es den Nutzern ermöglichen, ihre Bedürfnisse zu erfüllen? Welche Anrufe müssen sie zum Beispiel tätigen, um ihre Ziele zu erreichen? Wie wird ihnen der Status von Aufrufen mitgeteilt? Welche Art von Kontrollen, Filtern und Nutzungshinweisen wirst du ihnen in der Benutzeroberfläche zur Verfügung stellen?
Sicherheit: Welche Designmerkmale werden deinen Nutzern helfen, Fehler zu vermeiden? Wie wirst du Fehler und Probleme vermitteln?
Konsistenz: Welchen Grad an Vertrautheit wirst du deinen Nutzern bieten? Wird die API in Bezug auf andere APIs in deiner Organisation oder deiner Branche konsistent sein? Wird das Design der Schnittstelle anderen APIs ähneln, die deine Nutzer vielleicht schon verwendet haben, oder wird es sie mit seiner Innovation überraschen? Wirst du bei deinem Design ratifizierte Industriestandards übernehmen?

Diese Liste ist nicht erschöpfend, aber wie du siehst, gibt es eine Menge Entscheidungsgrundlagen, die du abdecken musst. Eine gute Schnittstelle zu entwerfen ist eine schwierige Aufgabe. Aber lass uns genauer sagen, was das Ziel ist. Was ist ein gutes Design für die Schnittstelle einer API und wie triffst du bessere Designentscheidungen?

Was ist gutes Design?

Wenn du dir die Arbeit gemacht hast, eine Strategie für deine API zu entwickeln, dann hast du bereits ein strategisches Ziel für deine API definiert. Nun müssen wir herausfinden, wie die Gestaltung der Schnittstelle dir helfen kann, diesem Ziel näher zu kommen. Wie wir in "Strategie" gesehen haben , kannst du dir viele verschiedene Ziele und Taktiken für eine API ausdenken. Aber im Allgemeinen laufen sie alle auf eine Entscheidung zwischen zwei gemeinsamen Zielen hinaus:

Gewinnen Sie mehr API-Nutzer.
Reduziere die Entwicklungskosten für die API-Nutzung.

In der Praxis brauchst du einen viel differenzierteren Blick auf die Strategie, wenn du effektiv sein willst. Aber wenn wir die Ziele auf diese Weise verallgemeinern, können wir eine wichtige Beobachtung machen: Ein gutes Oberflächendesign wird dir helfen, beide Ziele zu erreichen. Wenn das Gesamterlebnis bei der Nutzung der API gut ist, werden mehr Nutzer bereit sein, sie zu nutzen. Das Oberflächendesign spielt eine große Rolle für die Erfahrung der Entwickler mit deiner API, daher sollte ein gutes Oberflächendesign zu einer höheren Nutzerakquise führen. Eine gute Benutzeroberfläche macht es außerdem schwieriger, die falschen Dinge zu tun, und einfacher, die Probleme der Nutzer/innen zu lösen. Das führt zu einem geringeren Entwicklungsaufwand für die Software, die du schreibst, wenn du eine gut gestaltete API verwendest.

Es lohnt sich also, in gutes Interface-Design zu investieren. Aber es gibt keine konkrete Anzahl von Entscheidungen, die eine Schnittstelle zu einer "guten" Schnittstelle machen. Die Qualität deiner Benutzeroberfläche hängt ganz von den Zielen deiner Nutzer ab. Es ist unmöglich, die Benutzerfreundlichkeit und das Nutzererlebnis zu verbessern, wenn du nicht weißt, für wen du designst. Wenn du dir bereits überlegt hast, warum du diese API baust, ist es zum Glück eine einfache Übung, herauszufinden, für wen du sie gestaltest. Richte dich an diese Nutzergemeinschaft und treffe Designentscheidungen, die ihre Erfahrung bei der Nutzung deiner API verbessern.

Verwendung einer Entwurfsmethode

Um die besten Ergebnisse bei der Gestaltung von Benutzeroberflächen zu erzielen, ist es am besten, wenn du eine Methode oder einen Prozess anwendest. Ein großer Teil der Arbeit an einem Entwurf besteht darin, dass du Vermutungen oder Annahmen darüber anstellst, was deiner Meinung nach funktionieren wird. Du musst irgendwo anfangen, also kopierst du vielleicht zunächst eine API-Schnittstelle, die dir gefällt, oder befolgst eine Anleitung in einem Blogbeitrag. Das ist völlig in Ordnung. Aber wenn du den Wert deiner Design-Schnittstelle maximieren willst, brauchst du eine Möglichkeit, diese Annahmen zu testen und sicherzustellen, dass die von dir getroffenen Entscheidungen die besten sind.

Wir könnten uns zum Beispiel für den folgenden leichtgewichtigen Prozess entscheiden:

Entwirf einen Prototyp für die Benutzeroberfläche.
Schreibe unseren eigenen Client, der den Prototyp verwendet.
Aktualisiere den Prototyp anhand der gewonnenen Erkenntnisse und probiere ihn noch einmal aus.

Ein schwierigerer Prozess könnte so aussehen:

Veranstalte ein frühes Planungstreffen mit allen Interessengruppen (d.h. Nutzer/innen, Unterstützer/innen und Umsetzer/innen).
Entwirf ein Vokabular für die Schnittstelle.
Führe Umfragen in der Nutzergemeinschaft durch.
Erstelle einen Prototyp.
Teste den Prototyp mit den Zielgruppen.
Validiere den Prototyp mit den Umsetzern.
Iteriere nach Bedarf.

Der große Unterschied zwischen diesen beiden Beispielen ist der Umfang der Investitionen, die du tätigen musst, und die Menge an Informationen, die du sammeln musst. Die Entscheidung, wie viel du in den Designprozess investierst, ist eine strategische Entscheidung. Zum Beispiel wirst du die Schnittstelle einer externen API, die auf einem Konkurrenzmarkt verkauft wird, wahrscheinlich genauer unter die Lupe nehmen als eine interne API, die von deinem eigenen Entwicklungsteam verwendet wird. Aber erinnere dich daran, dass sich auch ein einfacher Entwurfsprozess auszahlen kann.

Wichtige Entscheidungen für die Design Governance

Was sind die Grenzen des Designs?: Ein API-Team, das keine Design-Zwänge hat, kann ein Schnittstellenmodell erstellen, das die Benutzerfreundlichkeit und das Erlebnis für seine Benutzer maximiert. Aber die Benutzerfreundlichkeit ist benutzerorientiert und geht auf Kosten der Flexibilität für die Benutzer im Allgemeinen. Das bedeutet, dass diese Art der lokalen Optimierung Auswirkungen auf das System hat. Wenn du viele APIs entwickelst und die Nutzer/innen mehr als eine davon verwenden müssen, musst du bei deinen Designentscheidungen einige Einschränkungen einführen. Das bedeutet, dass du entweder die Designarbeit zentralisieren musst oder die Auswahl an Möglichkeiten, die den Designern zur Verfügung stehen, zentralisieren musst. Einige zentralisierte Teams veröffentlichen einen "Styleguide", um diese Art von Designvorgaben zu dokumentieren; er kann die offiziell erlaubten Vokabeln, Stile und Interaktionen enthalten.
Wie werden Schnittstellenmodelle gemeinsam genutzt?: Wenn du entscheidest, wie das Modell einer Schnittstelle gemeinsam genutzt werden soll, musst du auch entscheiden, wie die Arbeit des API-Designs weitergeführt werden soll. Wenn du diese Entscheidung vollständig zentralisierst, kannst du zum Beispiel entscheiden, dass alle API-Teams Entwürfe im OpenAPI-Beschreibungsformat bereitstellen müssen. Dies hat den Nachteil, dass alle möglichen Designoptionen auf die in der OpenAPI-Spezifikation verfügbaren Optionen beschränkt sind, macht es aber auch einfacher, die Arbeit zwischen den Teams aufzuteilen und im gesamten System einheitliche Werkzeuge und Automatisierungen zu verwenden.

Dokumentation

No Egal, wie gut du die Schnittstelle deiner API gestaltest, deine Nutzer werden ohne ein wenig Hilfe nicht loslegen können. Du musst den Nutzern zum Beispiel beibringen, wo sich die API im Netzwerk befindet, wie das Vokabular der Nachrichten und der Schnittstelle lautet und in welcher Reihenfolge sie die Aufrufe tätigen sollen. Die Säule der API-Dokumentation fasst die Arbeit zusammen, die nötig ist, um diese API-Lernerfahrung zu schaffen. Wir nennen diese Säule "API-Dokumentation" anstelle von "API-Lernen", weil die beliebtesten API-Lernerfahrungen in Form einer von Menschen lesbaren Dokumentation bereitgestellt werden.

Eine gute Dokumentation lohnt sich aus demselben Grund, aus dem es sich lohnt, eine gute Schnittstelle zu entwerfen: Eine bessere Erfahrung für die Entwickler führt zu einem höheren strategischen Wert. Wenn du keine gute Dokumentation hast, ist die API schwieriger zu erlernen und zu verstehen. Wenn es zu schwierig ist, die Nutzung zu erlernen, werden weniger Menschen sie nutzen. Wenn sie gezwungen sind, sie zu benutzen, dauert die Entwicklung der Software länger und die Wahrscheinlichkeit von Fehlern ist größer. Die Entwicklung einer guten Dokumentation ist ein wichtiger Faktor für ein gutes Entwicklererlebnis.

Methoden der Dokumentation

Du kannst API-Dokumentation auf viele verschiedene Arten bereitstellen: Du kannst eine enzyklopädieähnliche Referenz zu den Ressourcen deiner API bereitstellen, du kannst Tutorials und konzeptionelle Inhalte bereitstellen und du kannst sogar hoch dokumentierte, komplexe Beispielanwendungen bereitstellen, die die Nutzer kopieren und von denen sie lernen können. Es gibt eine unglaubliche Vielfalt an Stilen, Formaten und Strategien für die technische Dokumentation. Um die Sache zu vereinfachen, unterteilen wir die API-Dokumentation in zwei grundlegende Praktiken: die Methode "teach don't tell" und die Methode "tell don't teach". Unserer Erfahrung nach musst du beide Methoden anwenden, wenn du die beste Lernerfahrung für deine Nutzer/innen schaffen willst.

Der tell don't teach-Ansatz für die Dokumentation konzentriert sich auf die Vermittlung von Fakten über deine API, die den Nutzern helfen, sie zu verwenden. Beispiele für diesen faktenbasierten Ansatz sind die Liste der Fehlercodes deiner API und die Liste der von ihr verwendeten Schemata für den Nachrichtenkörper. Diese Art von Dokumentation gibt deinen Nutzern einen Leitfaden für deine Schnittstelle an die Hand. Da sie sehr faktenbasiert ist, ist sie relativ einfach zu entwerfen und zu entwickeln. Mit Hilfe von Werkzeugen kannst du diese Art von Dokumentation sogar sehr schnell erstellen, vor allem, wenn der Entwurf der Schnittstelle in einem maschinenlesbaren Format erstellt wurde (siehe "API-Beschreibungsformate"). Insgesamt erfordert diese Art der sachlichen Berichterstattung über Schnittstellendetails und -verhalten einen geringeren Designaufwand und weniger Entscheidungsfindung seitens deines Teams. Die wichtigsten Entscheidungen betreffen eher die Frage, welche Teile der API dokumentiert werden müssen, als die Frage, wie diese Informationen am besten vermittelt werden können.

Umgekehrt konzentriert sich mit dem "teach don't tell" -Ansatz bei der Dokumentation auf die Gestaltung einer Lernerfahrung. Anstatt den Lesern nur die Fakten zu präsentieren, bietet dieser Ansatz den Nutzern eine maßgeschneiderte Lernerfahrung. Das Ziel ist es, deinen API-Nutzern dabei zu helfen, ihre Ziele zu erreichen und gleichzeitig zu lernen, wie sie deine API auf eine gezielte Art und Weise nutzen können. Wenn du zum Beispiel eine Karten-API besitzt, könntest du ein Tutorial in sechs Schritten schreiben, in dem du deinen Nutzern beibringst, wie sie GPS-Informationen für eine Adresse abrufen können. Auf diese Weise kannst du ihnen helfen, eine ziemlich typische Aufgabe mit einem Minimum an Aufwand zu erledigen.

Aber die Dokumentation muss nicht passiv sein. Referenzen, Leitfäden und Tutorials sind hilfreich, aber du kannst auch Tools bereitstellen, die deinen Nutzern helfen, deine API auf interaktive Weise kennenzulernen. Du kannst zum Beispiel ein webbasiertes API-Explorer-Tool bereitstellen, mit dem deine Nutzer/innen in Echtzeit Anfragen an deine API senden können. Ein gutes API-Explorer-Tool ist mehr als ein "dummes" Netzwerkanfrage-Tool; es leitet die Lernerfahrung, indem es dem Nutzer eine Liste von Aktivitäten, Vokabeln, Vorschlägen und Korrekturen zur Verfügung stellt. Der große Vorteil interaktiver Werkzeuge ist, dass sie die Feedback-Schleife für die Nutzer/innen verkürzen: den Zyklus, in dem sie etwas lernen, versuchen, das Gelernte anzuwenden, und aus den Ergebnissen lernen. Ohne Tools müssen deine Nutzer/innen Zeit damit verbringen, Code zu schreiben oder externe Tools zu finden und zu nutzen, was zu einer viel längeren Schleife führen kann.

Das Entwicklerportal

In der Welt der APIs ist ein Entwicklerportal der Ort (normalerweise eine Website), an dem alle zusätzlichen Ressourcen für eine API gehostet werden. Du musst nicht unbedingt ein Entwicklerportal haben, aber es kann dazu beitragen, die Erfahrung der Entwickler mit deiner API zu verbessern, indem es den Nutzern eine bequeme Möglichkeit bietet, dein Produkt kennenzulernen und mit ihm zu interagieren.

In die Dokumentation investieren

Wenn du nur eine Art von API-Dokumentation bereitstellst, ist die Wahrscheinlichkeit groß, dass du deiner Nutzergemeinschaft nicht gerecht wirst. Verschiedene Nutzer/innen haben unterschiedliche Bedürfnisse und du musst auf jede/n von ihnen eingehen, wenn dir ihre Lernerfahrung wichtig ist. Neue Nutzer/innen können zum Beispiel sehr von der "teach don't tell" -Dokumentation profitieren, weil sie vorschreibend und einfach zu befolgen ist, aber Nutzer/innen, die bereits Erfahrung mit deiner API haben, werden deine "tell don't teach" -Dokumentation zu schätzen wissen, weil sie schnell zu den Fakten navigieren können, die sie brauchen. Ebenso können interaktive Tools Nutzer/innen ansprechen, die ein Live-Erlebnis genießen, aber sie sind nicht geeignet für Nutzer/innen, die lieber verstehen und planen - oder die einfach lieber lesen wollen.

In der Praxis kann die Bereitstellung der gesamten Dokumentation für deine API kostspielig sein. Schließlich muss jemand die gesamte Dokumentation entwerfen und schreiben - und das nicht nur einmal, sondern während der gesamten Lebensdauer deiner API. Unter besteht eine der Schwierigkeiten bei der API-Dokumentation darin, dass sie mit den Änderungen an den Schnittstellen und Implementierungen synchronisiert werden muss. Wenn die Dokumentation falsch ist, können die Nutzer sehr schnell unzufrieden werden. Du musst also klug entscheiden, wie viel Dokumentationsaufwand für dein API-Produkt nachhaltig ist.

Der wichtigste Faktor bei der Entscheidung über die Investition in die Dokumentation sollte der Wert sein, den die Verbesserung der Lernerfahrung der API für dein Unternehmen hat. Eine gute Dokumentation kann zum Beispiel dazu beitragen, ein öffentliches API-Produkt von seinen Mitbewerbern zu unterscheiden. Sie kann auch eine große Hilfe für eine interne API sein, die von Entwicklern genutzt wird, die mit dem System, dem Geschäft oder der Branche des API-Eigentümers nicht vertraut sind. Der Dokumentationsaufwand für eine öffentliche API, die in einem Wettbewerbsmarkt tätig ist, ist in der Regel höher als für eine interne API, und das ist auch gut so. Letztendlich musst du entscheiden, wie viel Dokumentation für deine API gut genug ist. Die gute Nachricht ist, dass es immer möglich ist, diese Investition zu erhöhen, wenn deine API wächst.

Wichtige Entscheidungen für die Verwaltung der Dokumentation

Wie sollte die Lernerfahrung gestaltet sein?: Entscheidungen über die Gestaltung von Lernerfahrungen werden oft unabhängig von der Gestaltung, Implementierung und Bereitstellung einer API getroffen. Wenn du viele APIs hast, werden deine Nutzer/innen es zu schätzen wissen, wenn sie ein einheitliches Lernerlebnis für alle haben. Die Zentralisierung dieser Entscheidung ist jedoch mit den üblichen Kosten verbunden: weniger Innovation und mehr Einschränkungen für die API-Teams sowie ein potenzieller Engpass bei der zentralisierten technischen Redaktion. Du musst abwägen zwischen dem Bedürfnis nach Konsistenz und dem Maß an Vielfalt und Innovation, das du unterstützen musst. Eine Möglichkeit ist die Einführung eines Hybridmodells, bei dem die meisten APIs zentral dokumentiert werden, die Teams aber ihre eigenen Lernerfahrungen machen können, wenn sie etwas Neues ausprobieren.
Wann sollte eine Dokumentation geschrieben werden?: Es gibt erstaunlich viele Unterschiede bei der Frage, wann ein Team mit der Erstellung seiner Dokumentation beginnen sollte. Eine frühzeitige Erstellung ist teurer, weil es wahrscheinlich zu Änderungen am Design und an der Implementierung kommt, aber sie kann Probleme mit der Benutzerfreundlichkeit frühzeitig aufdecken, so dass es sich lohnt. Ihr müsst entscheiden, ob diese Entscheidung dezentral getroffen werden kann oder ob sie zentraler verwaltet werden muss. Muss zum Beispiel jede API unabhängig von ihrem Verwendungszweck eine schriftliche Dokumentation haben, bevor sie freigegeben werden kann? Oder sollten die Teams diese Entscheidung nach bestem Wissen und Gewissen treffen?

Entwicklung

Die Säule der API-Entwicklung umfasst alle Entscheidungen, die du triffst, wenn du deine API zum "Leben" erweckst. Das ist die harte Arbeit, die du leisten musst, um die Implementierung deiner API so zu entwickeln, dass sie ihrem Oberflächendesign treu bleibt. Die Säule der Entwicklung hat einen überwältigend großen Entscheidungsspielraum. Du musst entscheiden, welche Technologieprodukte und Frameworks du für die Implementierung der API verwenden willst, wie die Architektur der Implementierung aussehen soll, welche Programmier- und Konfigurationssprachen verwendet werden müssen und wie sich die API zur Laufzeit verhalten soll. Mit anderen Worten: Du musst die Software für deine API entwerfen und entwickeln.

Die Wahrheit ist, dass es den Nutzern deiner API egal ist, wie du deine API implementierst. All deine Entscheidungen über Programmiersprachen, Tools, Datenbanken und Softwaredesign sind für sie bedeutungslos; nur das Endprodukt zählt. Solange die API das tut, was sie tun soll, und zwar auf die Art und Weise, wie sie es tun soll, werden deine Nutzer/innen zufrieden sein. Die Tatsache, dass du das mit einer bestimmten Datenbank oder einem bestimmten Framework schaffst, ist für deine Nutzer nur eine Nebensächlichkeit.

Aber nur weil deine Nutzer sich nicht für deine Entscheidungen interessieren, heißt das nicht, dass deine Entwicklungsentscheidungen nicht wichtig sind. Tatsächlich sind Entwicklungsentscheidungen sehr wichtig, vor allem für die Menschen, die die API während ihrer Lebensdauer entwickeln, pflegen und ändern müssen. Wenn du dich für Technologien entscheidest, die schwer zu benutzen sind, oder für esoterische Sprachen, die niemand in deinem Unternehmen versteht, wird die API schwieriger zu warten sein. Wenn du dich für Werkzeuge entscheidest, die dich zu sehr einschränken, oder für Sprachen, in denen du nur mühsam programmieren kannst, wird die API schwer zu ändern sein.

Wenn du über die Säule der API-Entwicklung nachdenkst, ist es leicht, sich nur auf die Entscheidungen zu konzentrieren, die du für die Erstellung der ersten Version des Produkts treffen musst. Das ist wichtig, aber es ist nur ein kleiner Teil der Herausforderung. Das wichtigere Ziel ist es, Entwicklungsentscheidungen zu treffen, die die Qualität, Skalierbarkeit, Änderbarkeit und Wartbarkeit deiner API während ihrer gesamten Lebensdauer verbessern. Um Software mit dieser Perspektive zu entwickeln, brauchst du Erfahrung und Können. Deshalb musst du gut in Menschen und Werkzeuge investieren. Schließlich kann jeder nach ein paar Programmierkursen ein Computerprogramm schreiben, aber es braucht einen echten Profi, um Programme zu schreiben, die in großem Maßstab und bei gleichzeitiger Nutzung funktionieren und die alle Kanten behandeln, die im wirklichen Leben auftreten, während sie von anderen Entwicklern gewartet und geändert werden können.

Es gibt keine konkreten Regeln dafür, wie du deine API-Software entwerfen und gestalten solltest, so wie es auch keine konkreten Regeln für die Gestaltung von Software im Allgemeinen gibt. Aber es gibt natürlich viele Anleitungen, Philosophien und Ratschläge, wie du deine Software gestalten solltest. Im Allgemeinen kannst du alle bewährten Verfahren für die serverbasierte Entwicklung auf die API-Entwicklung anwenden. Das Einzige, was für APIs besonders ist, ist das gesunde Ökosystem von API-spezifischen Frameworks und Werkzeugen für die Entwicklung von Instanzen. Werfen wir einen Blick auf die Möglichkeiten, die du hast, um die Vorteile dieser Hilfsmittel zu nutzen.

Rahmenwerke und Werkzeuge nutzen

Eine große Vielfalt an Tools wird in jedem typischen Entwicklungsprozess verwendet, aber bei der API-Entwicklung sind wir an einer bestimmten Kategorie von Tools interessiert - der Art, die dir hilft, die API-bezogenen Entscheidungen und den Entwicklungsaufwand bei der Erstellung einer neuen API-Version zu erleichtern. Dazu gehören Frameworks, die das Schreiben von API-Code erleichtern, sowie eigenständige Tools, die eine "no-code" oder "low-code" Implementierung bieten.

Ein Tool, das im Bereich der API-Verwaltung besonders beliebt ist, ist das API-Gateway. Ein API-Gateway ist ein serverbasiertes Tool, das die Kosten für die Bereitstellung von APIs innerhalb eines Netzwerks senken soll. Sie sind in der Regel hoch skalierbar, zuverlässig und sicher - die Verbesserung der Sicherheit einer API-Implementierung ist oft die Hauptmotivation für die Einführung eines Gateways in einer Systemarchitektur. Sie sind nützlich, weil sie die Kosten für die Entwicklung einer API-Instanz erheblich senken können.

Die Entwicklungskosten sinken, wenn du ein Tool wie ein Gateway verwendest, weil es die meisten deiner Probleme lösen kann. In den meisten Fällen erfordern diese Tools sogar nur sehr wenig Programmieraufwand. Ein gutes HTTP-API-Gateway sollte zum Beispiel in der Lage sein, auf einem HTTPS-Port auf Anfragen zu warten, JSON-Anfragen zu analysieren und mit einer Datenbank zu interagieren, ohne dass du dafür etwas konfigurieren musst. Natürlich geschieht das alles nicht auf magische Weise; jemand musste dieses Tool so programmieren, dass es all diese Dinge kann. Letztendlich wälzt du die Kosten für die API-Entwicklung auf eine externe Agentur ab.

Wenn Tools gut funktionieren, sind sie ein Geschenk des Himmels. Der Preis für den Einsatz von Tools wie API-Gateways ist jedoch, dass sie nur das tun können, wofür sie entwickelt wurden. Wie bei jeder Maschine ist deine Flexibilität auf die Funktionen beschränkt, die die Maschine bietet. Die Wahl des richtigen Werkzeugs ist also eine wichtige Entwicklungsentscheidung. Wenn deine API-Strategie und das Oberflächendesign von in die Richtung gehen, dass du viele nicht standardisierte Dinge tun willst, musst du möglicherweise einen größeren Teil der Entwicklungsarbeit selbst in die Hand nehmen.

Die Beziehung zwischen Schnittstelle und Implementierung

Unterstützen die Strategie und das Schnittstellendesign deiner API ist wirklich das wichtigste Ziel deiner Entwicklungsarbeit. Egal, wie gut deine Architektur ist und wie wartungsfreundlich dein Code ist, wenn die API nicht das tut, was sie laut Schnittstellendesign tun soll, hast du fehlgeschlagen. Aus dieser Aussage können wir zwei Schlussfolgerungen ziehen:

Die Konformität mit deinem veröffentlichten Oberflächendesign ist ein wichtiger Qualitätsmaßstab für deine Implementierung.
Du musst deine Implementierung immer wieder aktualisieren, wenn du die Schnittstelle änderst.

Das bedeutet, dass du deine API erst dann entwickeln kannst, wenn du ein Interface-Design hast. Das bedeutet auch, dass die Leute, die an der Entwicklung arbeiten, eine zuverlässige Methode brauchen, um zu verstehen, wie die Schnittstelle aussieht und wann sie sich ändert. Ein großes Risiko für dein API-Produkt besteht darin, dass sich das Designteam für ein Schnittstellendesign entscheidet, das unpraktisch oder unmöglich zu implementieren ist. Wenn der Schnittstellendesigner und der Implementierungsentwickler ein und dieselbe Person sind oder im selben Team arbeiten, ist das keine große Sache, aber wenn das nicht der Fall ist, solltest du sicherstellen, dass die Überprüfung der Schnittstelle durch das Implementierungsteam Teil deiner API-Designmethode ist.

API-Beschreibungen in der Nähe des Codes verwenden

Eine Möglichkeit, die Synchronisierung von Implementierung und Schnittstelle zu verbessern, besteht darin, die Schnittstellenbeschreibung in deine Implementierung zu integrieren. Wenn du zum Beispiel ein API-Beschreibungsformat hast, das den Entwurf der Schnittstelle darstellt, kannst du diese Datei in deinem Code-Repository aufbewahren oder sogar einen automatisierten Test entwickeln, der die Einhaltung der Schnittstelle überprüft. Darüber hinaus kannst du sogar ein Codeskelett auf der Grundlage des Beschreibungsformats erstellen - auch wenn das nur für die erste Version sinnvoll ist.

Du kannst auch den umgekehrten Weg gehen: Anstatt eine Schnittstellenbeschreibung zu erhalten und sie in deinem Code zu verwenden, kannst du die Schnittstellenbeschreibung von Hand direkt in deinen Code einbetten. Einige Frameworks erlauben es dir zum Beispiel, Anmerkungen zu verwenden, die eine API-Schnittstelle beschreiben. Die Kombination aus deinem Code und den Schnittstellen-Anmerkungen kann zur "Quelle der Wahrheit" für deine Schnittstelle werden und du kannst sie sogar zur Erstellung von API-Dokumentation verwenden. Jeder dieser Ansätze kann nützlich sein, um sicherzustellen, dass deine Implementierung nicht gegen ein Versprechen verstößt, das dein Schnittstellendesign gibt.

Wichtige Entscheidung für die Entwicklungspolitik

Was kann für die Umsetzung genutzt werden?

Diese ist die zentrale Governance-Frage für die Umsetzung. Es ist eine weitreichende Frage, die viele Entscheidungen beinhaltet: Welche Datenbanken, Programmiersprachen und Systemkomponenten kannst du auswählen? Welche Bibliotheken, Frameworks und Tools können zur Unterstützung der Arbeit verwendet werden? Mit welchen Anbietern musst du zusammenarbeiten? Darfst du Open-Source-Code verwenden?

Zum Zeitpunkt der Erstellung dieses Artikels gibt es ein großes Interesse an der Dezentralisierung dieser Art von Entscheidungen, um die lokale Optimierung zu verbessern. Wir haben von vielen Unternehmen gehört, die festgestellt haben, dass ihre APIs effizienter, einfacher zu erstellen und leichter zu warten sind, wenn die Teams mehr Freiheit bei der Umsetzung haben. Die Dezentralisierung ist jedoch mit den üblichen Kosten verbunden: weniger Konsistenz und weniger Möglichkeiten zur Systemoptimierung. In der Praxis bedeutet das, dass es für die Mitarbeiter schwieriger sein kann, zwischen den Teams zu wechseln, und dass es weniger Möglichkeiten gibt, Skaleneffekte zu erzielen und die Umsetzung im Allgemeinen weniger transparent zu machen.

Unserer Erfahrung nach lohnt es sich, mehr Freiheit bei der Umsetzung zu gewähren, aber du musst abwägen, wie viel Entscheidungsfreiheit sich dein System leisten kann. Eine Möglichkeit, dezentrale Umsetzungsentscheidungen zu erleichtern, ist die Zentralisierung der Auswahl, d.h. die Zentralisierung der Technologieoptionen und die Dezentralisierung der Auswahl und Befugnisse des Teams.

Testen

Wenn dir die Qualität deiner API am Herzen liegt, musst du sie auch testen. In der Säule der API-Tests musst du entscheiden, was du testen willst und wie du es testen willst. Im Allgemeinen unterscheidet sich das Testen von APIs nicht sehr von der typischen Qualitätssicherung (QA), die du bei einem Softwareprojekt durchführst. Du solltest in der Lage sein, gute Software-Qualitätspraktiken auf die Implementierung, die Schnittstelle und die Instanzen deiner API anzuwenden, genau wie bei einer herkömmlichen Softwareanwendung. Aber wie bei der Entwicklung ist es das Ökosystem von Tools, Bibliotheken und Hilfsmitteln, das die API-Domäne etwas anders macht als den allgemeinen Testbereich.

Was muss getestet werden?

Das Hauptziel des Testens deiner API ist es, sicherzustellen, dass sie das strategische Ziel erreicht, das du bei ihrer Erstellung festgelegt hast. Aber wie wir in diesem Kapitel gesehen haben, wird dieses strategische Ziel durch die entscheidungsbasierte Arbeit der 10 Säulen ermöglicht. Das sekundäre Ziel der API-Prüfung besteht also darin, sicherzustellen, dass die gesamte Arbeit, die du in unseren Pfeilern geleistet hast, von ausreichender Qualität ist, um die Strategie zu unterstützen. Wenn zum Beispiel die Benutzerfreundlichkeit und die Lernfähigkeit deiner API sehr niedrig sind, könnte sich das auf das strategische Ziel auswirken, mehr API-Nutzer zu gewinnen. Das bedeutet, dass du spezifische Tests definieren musst, um die Qualität der Schnittstelle zu bewerten. Außerdem musst du prüfen, ob die von dir geleistete Arbeit intern konsistent ist. Zum Beispiel musst du prüfen, ob die von dir entwickelte Implementierung mit der von dir entworfenen Schnittstelle übereinstimmt.

Hier ist eine typische Liste von Prüfkategorien, die API-Besitzer/innen verwenden:

Usability- und UX-Tests: Identifiziere Benutzerfreundlichkeitsfehler in der Schnittstelle, der Dokumentation und der Entdeckung. Zum Beispiel: stelle die API-Dokumentation für Entwickler bereit und führe "über die Schulter" Beobachtungstests durch, während sie versuchen, Client-Code damit zu schreiben.
Einheitstests: Identifiziere Fehler innerhalb der Implementierung auf einer granularen Ebene. Ein Beispiel: Führe bei jedem Build einen JUnit-Test gegen eine Java-Methode im Code der API-Implementierung durch.
Integrationstests: Identifiziere die Implementierung und Schnittstellenfehler, indem du API-Aufrufe gegen eine Instanz machst. Ein Beispiel: Führe ein Testskript aus, das API-Aufrufe gegen eine laufende Instanz der API in einer Entwicklungsumgebung tätigt.
Leistungs- und Lasttests: Identifiziere nicht funktionierende Fehler in eingesetzten API-Instanzen und Instanzumgebungen. Beispiel: Führe ein Leistungstest-Skript aus, das eine Belastung auf Produktionsniveau mit einer laufenden Instanz der API in einer produktionsähnlichen Testumgebung simuliert.
Sicherheitstests: Identifiziere Sicherheitsschwachstellen in der Schnittstelle, der Implementierung und der Instanz der API. Beispiel: Beauftrage ein "Tigerteam" damit, Schwachstellen in einer laufenden Instanz der API in einer sicheren Testumgebung zu finden.
Produktionstests: Identifiziere Fehler in der Benutzerfreundlichkeit, Funktionalität und Leistung, nachdem das API-Produkt in der Produktionsumgebung veröffentlicht wurde. Beispiel: Führe einen multivariaten Test mit der API-Dokumentation durch, bei dem verschiedenen Nutzern leicht unterschiedliche Versionen des Inhalts angezeigt werden, und verbessere die Benutzerfreundlichkeit der Dokumentation anhand der Ergebnisse.

Diese Liste ist sicher nicht vollständig und es gibt noch viele andere Tests, die du durchführen kannst. Sogar die Tests, die wir hier beschrieben haben, könnten in viele weitere Unterkategorien aufgeteilt werden. Die große strategische Entscheidung, die du im Bereich der Tests treffen musst, ist die Frage, wie viel Tests gut genug sind. Im Idealfall kann dir deine API-Strategie dabei helfen, diese Entscheidung zu treffen. Wenn Qualität und Konsistenz eine hohe Priorität haben, musst du vielleicht viel Zeit und Geld in das Testen deiner API investieren, bevor sie veröffentlicht werden kann. Wenn deine API jedoch experimentell ist, kannst du einen risikotoleranten Ansatz wählen und ein Mindestmaß an Tests durchführen. Wir gehen zum Beispiel davon aus, dass die Testrichtlinien für die Zahlungsverkehrs-API einer etablierten Bank und die Social-Networking-API eines Start-ups sehr unterschiedlich ausfallen.

API-Testwerkzeuge

Testen kann teuer sein, deshalb ist es hilfreich, Prozessverbesserungen einzuführen, die es einfacher machen, die Qualität deines Produkts zu verbessern. Einige Unternehmen haben zum Beispiel Erfolg mit einer "testgetriebenen" Methode, bei der die Tests geschrieben werden , bevor die Implementierung oder Schnittstelle erstellt wird. Das Ziel dieses Ansatzes ist es, die Kultur eines Teams so zu verändern, dass alle Designentscheidungen zu einer testfreundlichen Implementierung führen. Wenn es funktioniert, ist das Ergebnis eine API, die aufgrund ihrer impliziten Testbarkeit von höherer Qualität ist.

Zusätzlich zu den Prozess- und Kulturverbesserungen kannst du Werkzeuge und Automatisierung nutzen, um die Kosten für die Durchführung von Tests zu senken. Die nützlichsten Werkzeuge im Arsenal der API-Tests sind Simulatoren und Test-Doubles oder Mocks. Die vernetzte Natur von API-Software macht es schwierig, Dinge isoliert zu testen, daher brauchst du eine Möglichkeit, andere Komponenten zu simulieren. Vor allem brauchst du wahrscheinlich Werkzeuge, um jede dieser Komponenten zu simulieren:

Kunde: Wenn du deine API testest, brauchst du etwas, das die Anfragen simuliert, die von deinen API-Kunden kommen. Es gibt viele Tools, die das für dich tun können. Die guten Tools bieten dir genügend Konfigurationsmöglichkeiten und Variabilität, um den Arten von Nachrichten und Verkehrsmustern, die du in der Produktion erhalten wirst, sehr nahe zu kommen.
Backend: Die Wahrscheinlichkeit ist groß, dass deine API einige eigene Abhängigkeiten hat. Dabei kann es sich um eine Reihe interner APIs, eine Datenbank oder eine externe Ressource handeln. Um Integrationstests, Leistungstests und Sicherheitstests durchführen zu können, brauchst du wahrscheinlich eine Möglichkeit, diese Abhängigkeiten zu simulieren.
Umwelt: Außerdem brauchst du eine Möglichkeit, deine Produktionsumgebung zu simulieren, wenn du Vorproduktionstests durchführst. Vor Jahren bedeutete das, dass du eine geplante Umgebung nur für diesen Zweck unterhalten und betreiben musstest. Heutzutage nutzen viele Unternehmen Virtualisierungswerkzeuge, um die Erstellung von Testumgebungen kostengünstiger zu gestalten.
API: Manchmal wirst du sogar deine eigene API simulieren müssen. Das kann der Fall sein, wenn du eine deiner unterstützenden Komponenten testen willst - zum Beispiel einen API-Explorer in einem Entwicklungsportal, der die API aufruft -, aber eine simulierte Version deiner API ist auch eine wertvolle Ressource, die du den Nutzern deiner API zur Verfügung stellen kannst. Diese Art von simulierter API wird oft als Sandkasten bezeichnet, vermutlich weil es ein Ort ist, an dem Entwickler mit deiner API und deinen Daten spielen können, ohne dass es Konsequenzen hat. Es ist eine kleine Investition, aber sie kann die Erfahrung der Entwickler mit deiner API erheblich verbessern.

Dein Sandkasten soll sich wie eine Produktion anfühlen

Wenn du eine Sandbox für die Nutzer deiner API freigibst, solltest du sicherstellen, dass deine Sandbox die Produktionsumgebung so genau wie möglich reproduziert. Deine Nutzerinnen und Nutzer werden viel zufriedener sein, wenn die einzige Änderung, die sie vornehmen müssen, wenn sie ihren Code schreiben, darin besteht, ihn auf deine Produktionsinstanz zu verweisen. Nichts ist frustrierender, als viel Zeit und Energie in die Fehlersuche bei einer API-Integration zu investieren, nur um dann festzustellen, dass die Produktionsinstanz anders aussieht und sich anders verhält.

Wichtige Entscheidungen für die Steuerung von Tests

Wo sollen die Tests stattfinden?: Im Laufe der Jahre wurden die Prüfprozesse immer mehr dezentralisiert. Die große Governance-Entscheidung besteht darin, festzulegen, wie stark du die einzelnen Arten von API-Prüfungen, die wir beschrieben haben, zentralisieren oder dezentralisieren willst. Die Zentralisierung eines Prüfprozesses gibt dir mehr Kontrolle, hat aber auch den Preis eines möglichen Engpasses. Ein Teil davon kann durch Automatisierung gemildert werden, aber dann musst du entscheiden, wer das automatisierte System konfiguriert und pflegt. Die meisten Unternehmen setzen sowohl zentrale als auch dezentrale Systeme ein. Wir raten dazu, die frühen Testphasen zu dezentralisieren, um schneller zu sein, und die späteren Phasen aus Sicherheitsgründen zu zentralisieren.
Wie viel Prüfung ist genug?: Selbst wenn du entscheidest, dass die einzelnen Teams ihre eigenen Tests durchführen können, solltest du die Entscheidung über das Mindestmaß an Tests, das sie durchführen müssen, zentralisieren. Einige Unternehmen verwenden zum Beispiel Tools zur Codeabdeckung, die Auskunft darüber geben, wie viel des Codes getestet wurde. In Bezug auf Kennzahlen und Qualität ist die Codeabdeckung zwar nicht perfekt, aber sie ist quantifizierbar und ermöglicht es dir, einen Mindestwert festzulegen, den alle Teams erfüllen müssen. Wenn du die richtigen Leute hast, kannst du diese Entscheidung auch dezentralisieren und es den einzelnen API-Teams überlassen, das zu tun, was für ihre APIs richtig ist.

Einsatz

Die Implementierung einer API ist das, was die Schnittstelle zum Leben erweckt, aber diese Implementierung muss richtig eingesetzt werden, um nützlich zu sein. Die Säule der API-Bereitstellung umfasst die gesamte Arbeit, die nötig ist, um die Implementierung einer API in eine Umgebung zu bringen, in der deine Zielnutzer sie nutzen können. Die bereitgestellte API wird als Instanz bezeichnet, und du musst möglicherweise mehrere dieser Instanzen verwalten, damit deine API ordnungsgemäß funktioniert. Die Herausforderung bei der API-Bereitstellung besteht darin, dafür zu sorgen, dass sich alle Instanzen einheitlich verhalten, für deine Nutzer/innen verfügbar bleiben und so einfach wie möglich zu ändern sind.

Der Einsatz von Software ist heute viel komplizierter als in der Vergangenheit. Das liegt vor allem daran, dass unsere Software-Architekturen immer komplexer geworden sind und mehr Abhängigkeiten untereinander bestehen als je zuvor. Außerdem haben Unternehmen ziemlich hohe Erwartungen, wenn es um die Verfügbarkeit und Zuverlässigkeit von Systemen geht - sie erwarten, dass alles immer und zu jeder Zeit funktioniert. Oh, und vergiss nicht, dass sie wollen, dass Änderungen sofort veröffentlicht werden. Damit du all diese Erwartungen erfüllen kannst, musst du gute Entscheidungen über dein API-Bereitstellungssystem treffen.

Umgang mit Unsicherheit

Um die Qualität einer API-Bereitstellung zu verbessern, muss sichergestellt werden, dass sich deine API-Instanzen so verhalten, wie die Nutzer es erwarten. Ein großer Teil der Arbeit, die dafür nötig ist, findet natürlich außerhalb der Bereitstellung statt. Du musst guten, sauberen Implementierungscode schreiben und ihn gründlich testen, wenn du in der Produktion weniger Fehler haben willst. Aber selbst wenn du all diese Vorsichtsmaßnahmen triffst, passieren in der Produktion manchmal schlimme Dinge. Das liegt daran, dass eine veröffentlichte API ein hohes Maß an Unsicherheit und Unvorhersehbarkeit mit sich bringt.

Was passiert zum Beispiel, wenn es einen plötzlichen Anstieg der Nachfrage nach deinem API-Produkt gibt? Werden deine API-Instanzen in der Lage sein, die Last zu bewältigen? Oder was ist, wenn ein Betreiber versehentlich eine ältere Version einer API-Instanz einsetzt oder ein Drittanbieterdienst, von dem deine API abhängt, plötzlich nicht mehr verfügbar ist? Ungewissheit kann an vielen verschiedenen Stellen auftreten: durch deine Nutzer/innen, durch menschliches Versagen, durch deine Hardware und durch externe Abhängigkeiten. Um die Sicherheit bei der Bereitstellung zu erhöhen, musst du zwei gegensätzliche Ansätze verfolgen: Du musst Unsicherheiten beseitigen und sie gleichzeitig akzeptieren.

Eine beliebte Methode zur Beseitigung von Unsicherheiten beim API-Einsatz ist das Prinzip der Unveränderlichkeit. Unveränderlichkeit ist die Eigenschaft, dass sie nicht verändert werden kann - mit anderen Worten, sie ist "schreibgeschützt". Du kannst die Unveränderbarkeit auf viele Arten anwenden. Wenn du zum Beispiel deinen Mitarbeitern nicht erlaubst, die Umgebungsvariablen eines Servers zu ändern oder Softwarepakete manuell zu installieren, kannst du sagen, dass du eine unveränderliche Infrastruktur hast. In ähnlicher Weise kannst du unveränderliche API-Bereitstellungspakete erstellen, d. h. ein bereitstellbares Paket, das nicht verändert, sondern nur ersetzt werden kann. Das Prinzip der Unveränderlichkeit verbessert die Sicherheit, weil es die Unsicherheiten, die durch menschliche Eingriffe entstehen, ausschaltet.

Allerdings wirst du die Unsicherheit nie ganz ausschalten können. Du kannst nicht alle Eventualitäten vorhersagen und nicht alle Möglichkeiten testen. Ein großer Teil deiner Entscheidungsarbeit wird also darin bestehen, herauszufinden, wie du dein System auch dann sicher machen kannst, wenn das Unerwartete eintritt. Ein Teil dieser Arbeit findet auf der Ebene der API-Implementierung statt (z. B. das Schreiben von defensivem Code) und ein Teil auf der Landschaftsebene (z. B. das Entwerfen einer widerstandsfähigen Systemarchitektur), aber ein großer Teil der Arbeit muss auf der Ebene der Bereitstellung und des Betriebs stattfinden. Wenn du zum Beispiel den Zustand deiner API-Instanzen und Systemressourcen kontinuierlich überwachen kannst, kannst du Probleme finden und beheben, bevor sie sich auf deine Nutzer/innen auswirken.

Resiliente Software entwerfen

Eine unserer Lieblingsressourcen zur Verbesserung der Sicherheit einer bereitgestellten API ist Michael Nygards Buch Release It! (Pragmatic Bookshelf). Wenn du es noch nicht gelesen hast, solltest du das unbedingt nachholen. Es ist eine Fundgrube für Implementierungs- und Bereitstellungsmuster, mit denen du die Sicherheit und Widerstandsfähigkeit deines API-Produkts verbessern kannst.

Eine Art von Ungewissheit, die du in Kauf nehmen musst, sind Änderungen an der API. Es wäre zwar schön, wenn du alle Änderungen einfrieren könntest, sobald deine API zuverlässig funktioniert, aber Veränderungen sind unvermeidlich und du musst dich darauf vorbereiten. Tatsächlich sollte es ein Ziel deiner Arbeit sein, Änderungen so schnell wie möglich zu implementieren.

Automatisierung des Einsatzes

Es gibt eigentlich nur zwei Möglichkeiten, um deine Einsätze zu beschleunigen: weniger Arbeit zu machen oder schneller zu arbeiten. Manchmal kannst du das erreichen, indem du deine Arbeitsweise änderst - zum Beispiel, indem du eine andere Arbeitsweise oder eine neue Art von Kultur einführst. Das ist hart, aber es kann wirklich helfen. Auf dieses Thema werden wir später noch genauer eingehen, wenn wir in Kapitel 8 über Menschen und Teams sprechen.

Eine weitere Möglichkeit, um schneller zu werden, ist, menschliche Bereitstellungsaufgaben durch Automatisierung zu ersetzen. Wenn du zum Beispiel den Prozess des Testens, Erstellens und Bereitstellens deines API-Codes automatisierst, kannst du Releases auf Knopfdruck durchführen.

Der Einsatz von Werkzeugen und Automatisierung kann ein schneller Gewinn sein, aber sei dir der langfristigen Kosten bewusst. Die Einführung von Automatisierung in deinem Arbeitsablauf ist wie die Einführung von Maschinen in einer Fabrik - sie steigert die Effizienz, aber sie schränkt deine Flexibilität ein. Die Automatisierung bringt auch Anlauf- und Wartungskosten mit sich. Es ist unwahrscheinlich, dass sie von Anfang an funktioniert und dass sie sich von selbst an deine sich ändernden Anforderungen und Rahmenbedingungen anpasst. Wenn du also dein System durch Automatisierung verbesserst, musst du dich darauf einstellen, dass du diese Kosten im Laufe der Zeit bezahlen musst - das heißt, die Kosten für die Wartung der Maschinen und den eventuellen Ersatz.

APIOps: DevOps für APIs

vieles von dem, was wir in diesem Abschnitt beschrieben haben, passt gut zur Philosophie der DevOps-Kultur. Es gibt sogar einen neuen Begriff für die Anwendung von DevOps-Praktiken auf APIs, der sich APIOps nennt. Wir sind der Meinung, dass DevOps gut in den API-Bereich passt und es sich lohnt, davon zu lernen, egal wie du es nennen willst.

Wichtige Entscheidungen für die Einsatzsteuerung

Wer entscheidet, wann eine Freigabe erfolgen kann?

Die Frage, wer die Freigabe erteilt, ist von zentraler Bedeutung für die Deployment Governance. Wenn du talentierte Leute hast, denen du vertrauen kannst, eine Architektur, die fehlertolerant ist, und eine Geschäftsdomäne, die gelegentliche Ausfälle verzeihen kann, kannst du die Entscheidung vollständig dezentralisieren. Andernfalls musst du herausfinden, welche Teile dieser Entscheidung zentralisiert werden müssen. Die Verteilung dieser Entscheidung ist in der Regel nuanciert. Du könntest z.B. "Push to Release" für vertrauenswürdige Teammitglieder aktivieren oder die Freigabe in eine Testumgebung verlagern, in der ein zentrales Team eine "Go/No-Go"-Entscheidung treffen kann. Verteile sie so, dass sie zu deinen Einschränkungen passt und die größtmögliche Geschwindigkeit bei einem angemessenen Maß an Sicherheit ermöglicht.

Wie werden die Einsätze verpackt?

In den letzten Jahren hat die Frage, wie Software verpackt und ausgeliefert wird, enorm an Bedeutung gewonnen. Sie hat sich als die Art von Entscheidung herausgestellt, die ein ganzes System allmählich in eine andere Richtung lenken kann. Die wachsende Beliebtheit von Containern hat es zum Beispiel billiger und einfacher gemacht, unveränderliche, Cloud-freundliche Implementierungen zu erstellen. Du musst dir überlegen, wer diese wichtige Entscheidung für dein Unternehmen treffen soll. Ein dezentraler, lokal optimierter Entscheidungsträger versteht vielleicht nicht die Auswirkungen auf Sicherheit, Kompatibilität und Skalierung, aber ein rein zentraler Entscheidungsträger hat vielleicht keine Lösung, die der Vielfalt der Implementierungen und der eingesetzten Software gerecht wird. Wie üblich ist es sinnvoll, die Entscheidung in irgendeiner Form einzuschränken und zu verteilen.

Neben der Frage nach Zentralisierung und Dezentralisierung musst du auch überlegen, welches Team am besten in der Lage ist, die qualitativ hochwertigsten Entscheidungen zu treffen. Sollen die Betriebs- und Middleware-Teams die Paketierungsoptionen festlegen? Ein Architekturteam? Oder sollen die Implementierungsteams die Entscheidung treffen? Die Verteilung der Talente ist hier ein wichtiger Faktor: Welche Teams haben die Leute, die die besten Einschätzungen vornehmen können?

Sicherheit

APIs machen es einfacher, Software miteinander zu verbinden, aber sie bringen auch neue Probleme mit sich. Die Offenheit von APIs macht sie zu einem potenziellen Ziel und bietet eine neue Art von Angriffsfläche. Es gibt mehr Türen, durch die man eindringen kann, und der Schatz ist größer! Du musst also etwas Zeit darauf verwenden, die Sicherheit deiner API zu verbessern. Die Säule der API-Sicherheit konzentriert sich auf die Entscheidungen, die du treffen musst, um die folgenden Sicherheitsziele zu erreichen:

Schutz deines Systems, der API-Clients und der Endnutzer vor Bedrohungen
Halten Sie Ihre API für die rechtmäßige Nutzung durch rechtmäßige Nutzer betriebsbereit
Schutz der Privatsphäre von Daten und Ressourcen

Hinter diesen drei einfachen Zielen verbirgt sich ein enorm komplexer Themenbereich. Ein großer Fehler, den API-Produktverantwortliche machen, ist die Annahme, dass die Sicherung einer API einfach nur ein paar technische Entscheidungen erfordert. Damit wollen wir nicht sagen, dass technologische Entscheidungen zur Sicherheit nicht wichtig sind - natürlich sind sie das! Aber wenn du deine API-Sicherheitssäule wirklich stärken willst, musst du den Kontext der sicherheitsrelevanten Entscheidungen ausweiten.

Einen ganzheitlichen Ansatz wählen

Um die Sicherheit deiner API wirklich zu verbessern, musst du sie zum Teil des Entscheidungsprozesses für alle in diesem Kapitel beschriebenen Säulen machen. Ein großer Teil davon ist die Implementierung von Sicherheitsfunktionen zur Laufzeit. Zunächst einmal musst du Identitäten extrahieren, Clients und Endnutzer authentifizieren, die Nutzung genehmigen und Ratenlimits implementieren. Du kannst vieles davon selbst schreiben oder den sichereren und schnelleren Ansatz wählen, indem du Werkzeuge und Bibliotheken implementierst, die das für dich erledigen.

Aber API-Sicherheit umfasst viele Dinge, die außerhalb der Interaktion zwischen Client und API-Software passieren. Kulturelle Veränderungen können die Sicherheit verbessern, indem sie den Ingenieuren und Designern eine Mentalität vermitteln, bei der die Sicherheit an erster Stelle steht. Es können Prozesse eingeführt werden, die verhindern, dass unsichere Änderungen in die Produktion gelangen oder dort verbleiben. Die Dokumentation kann überprüft werden, um sicherzustellen, dass sie nicht versehentlich Informationen preisgibt. Vertriebs- und Supportmitarbeiter können geschult werden, damit sie nicht versehentlich private Daten weitergeben oder bei Social-Engineering-Angriffen helfen.

Natürlich ist das, was wir gerade beschrieben haben, viel größer als der traditionelle Bereich der API-Sicherheit. Aber die Wahrheit ist, dass API-Sicherheit nicht für sich allein existieren kann. Sie ist Teil eines vernetzten Systems und muss als ein Element eines ganzheitlichen Sicherheitsansatzes für dein Unternehmen betrachtet werden. Es nützt nichts, so zu tun, als sei sie eine Insel ohne Verbindung zu deiner übergeordneten Sicherheitsstrategie. Die Leute, die dein System ausnutzen wollen, werden es sicher nicht so behandeln.

Du musst also Entscheidungen darüber treffen, wie du deine API-Arbeit mit der Sicherheitsstrategie deines Unternehmens vereinbaren kannst. Manchmal ist das recht einfach, manchmal ist es schwieriger. Eine der großen Herausforderungen bei APIs ist der Spagat zwischen dem Wunsch nach Offenheit und Benutzerfreundlichkeit und dem Wunsch, die Dinge zu sichern. Wie weit du in die eine oder andere Richtung gehst, sollte von deiner Unternehmensstrategie und den strategischen Zielen deiner API abhängen.

Wichtige Entscheidungen für Security Governance

Welche Entscheidungen müssen genehmigt werden?

Alle Entscheidungen, die in deinem Unternehmen getroffen werden, haben das Potenzial, eine Sicherheitslücke zu schaffen, aber es ist unmöglich, jede Entscheidung, die getroffen wird, zu überprüfen. Du musst herausfinden, welche Entscheidungen die größten Auswirkungen auf die Sicherheit deiner API haben und sicherstellen, dass diese Entscheidungen die besten sind. Das hängt stark von deinem Kontext ab. Gibt es "vertrauenswürdige" Bereiche in deiner Architektur, die sichere "Kanten" haben müssen? Haben die Designer und Implementierer bereits Erfahrung mit guten Sicherheitspraktiken? Findet die gesamte Arbeit intern statt oder arbeitest du mit externen Implementierern zusammen? All diese kontextbezogenen Faktoren können den Fokus deiner Entscheidungsbefugnis verändern.

Wie viel Sicherheit braucht eine API?

Ein großer Teil des Sicherheitsapparats ist die Standardisierung von Arbeitsentscheidungen zum Schutz des Systems und seiner Nutzer. So gibt es zum Beispiel Regeln darüber, wo Dateien gespeichert werden können oder welche Verschlüsselungsalgorithmen verwendet werden sollen. Eine zunehmende Standardisierung schränkt die Freiheit der Teams und der Mitarbeiter ein, innovativ zu sein. Im Sicherheitskontext wird dies in der Regel mit den Auswirkungen einer einzigen Fehlentscheidung gerechtfertigt, aber nicht alle APIs brauchen unbedingt das gleiche Maß an Kontrolle und Schutz. Eine API, die von externen Entwicklern für Finanztransaktionen genutzt wird, erfordert beispielsweise höhere Sicherheitsinvestitionen als eine API, die für die Protokollierung von Leistungsdaten verwendet wird. Aber wer trifft diese Entscheidung?

Wie immer sind der Kontext, das Talent und die Strategie die wichtigsten Faktoren. Die Zentralisierung dieser Entscheidung ermöglicht es dem Sicherheitsteam, eine pauschale Bewertung auf der Grundlage seines Verständnisses des Systemkontextes vorzunehmen. Manchmal können diese allgemeinen Regeln jedoch dazu führen, dass Dinge unter den Tisch fallen - vor allem, wenn API-Teams neue und innovative Dinge tun, die das zentrale Team nicht berücksichtigen konnte. Wenn die Entscheidung verteilt ist, können die Teams selbst eine Bewertungsentscheidung treffen, aber das erfordert ein ordentliches Maß an Sicherheitswissen im Team selbst. Wenn du in einem Bereich arbeitest, in dem Sicherheit und Risikominderung Priorität haben, kann es passieren, dass du die höchste Sicherheitsstufe für alles erzwingst, ohne Rücksicht auf den lokalen Kontext und die Auswirkungen auf die Geschwindigkeit.

12 API-Sicherheitsgrundsätze

Abgeleitet von der Sicherheitscheckliste von Yuri Subach, die auf APIs angewendet wurde, ist die folgende Checkliste der 12 wichtigsten Prinzipien der API-Sicherheit, die du verwenden kannst, um dein Team zu sicheren APIs zu führen:

API-Vertraulichkeit: Die Begrenzung des Zugriffs auf die Informationen ist die erste Regel der API-Sicherheit. Die über die API zugängliche Ressource darf nur autorisierten Nutzern zur Verfügung stehen und muss während der Übertragung, Verarbeitung oder im Ruhezustand vor unbeabsichtigten Empfängern geschützt sein.
API-Integrität: Die von der API bereitgestellten Informationen müssen stets vertrauenswürdig und korrekt sein. Die Ressource muss vor absichtlichen und unabsichtlichen Änderungen, Modifikationen oder Löschungen geschützt werden, und unerwünschte Änderungen müssen automatisch erkannt werden.
API-Verfügbarkeit: Verfügbarkeit ist eine Garantie für den zuverlässigen Zugriff auf die Informationen durch autorisierte Personen. Die Anforderungen an die Verfügbarkeit beziehen sich auf die Infrastruktur und die Anwendungen, kombiniert mit geeigneten technischen Prozessen in der Organisation.
Wirtschaftlichkeit des Mechanismus: API-Design und die Implementierung des Systems müssen so einfach wie möglich gehalten werden. Komplexe APIs sind schwer zu überprüfen und zu verbessern und sie sind fehleranfälliger. Aus Sicht der Sicherheit und der Benutzerfreundlichkeit ist Minimalismus eine gute Sache.
Fehlschlagsichere API-Standardwerte: Der Zugang zu einem API-Endpunkt/einer API-Ressource sollte standardmäßig verweigert werden und der Zugang sollte nur im Falle einer speziellen Erlaubnis gewährt werden. Eine gute API-Sicherheit folgt dem Schutzschema "wann der Zugang gewährt werden sollte" und nicht dem Schutzschema "wann der Zugang eingeschränkt werden sollte".
Vollständige Mediation: Der Zugriff auf alle Ressourcen einer API sollte immer validiert werden. Jeder Endpunkt muss mit einem Autorisierungsmechanismus ausgestattet sein. Dieser Grundsatz bringt Sicherheitsüberlegungen auf eine systemweite Ebene.
Offenes API-Design: Ein gutes API-Sicherheitsdesign sollte kein Geheimnis sein und muss dokumentiert werden und auf definierten Sicherheitsstandards und offenen Protokollen basieren. Die API-Sicherheit betrifft alle Beteiligten der Organisation und kann auch Partner oder Verbraucher einschließen.
Geringstes API-Privileg: Jeder API-Konsument des Systems sollte mit den minimalen API-Berechtigungen arbeiten, die für die Ausführung der Aufgabe erforderlich sind. Dadurch wird der Schaden begrenzt, der durch einen Unfall oder Fehler im Zusammenhang mit diesem speziellen API-Verbraucher entsteht.
Psychologische Akzeptanz: Eine wirksame API-Sicherheitsimplementierung sollte ein System schützen, aber die Nutzer des Systems nicht daran hindern, es ordnungsgemäß zu nutzen, oder sie davon abhalten, alle Sicherheitsanforderungen zu befolgen. Das API-Sicherheitsniveau muss auf den Grad der Bedrohung abgestimmt sein. Ein starker API-Sicherheitsmechanismus für nicht sensible Ressourcen kann für die Nutzer/innen einen unverhältnismäßig hohen Aufwand bedeuten.
Minimiere die Angriffsfläche für APIs: Die Begrenzung der Angriffsfläche für eine API ist die Minimierung dessen, was von böswilligen Nutzern ausgenutzt werden kann. Um die Angriffsfläche einer API zu verringern, kannst du nur das Nötigste offenlegen und den Schaden begrenzen, indem du den Umfang und die Rate begrenzst, die Anzahl der API-Aufrufe vor einer weiteren Benutzervalidierung drosselst und die Anwendungsfälle mit der nötigen Sorgfalt prüfst.
API-Verteidigung in der Tiefe: Mehrere Kontrollebenen machen es schwieriger, eine API auszunutzen. Du kannst den Zugang zum Server auf mehrere bekannte IP-Adressen beschränken (White Labeling), eine Zwei-Faktor-Authentifizierung einführen und viele andere Techniken implementieren, die deine API-Sicherheitspraxis verbessern.
Null-Vertrauens-Politik: Die Null-Vertrauens-Politik von bedeutet, dass wir Drittanbieter-APIs und Drittanbieter-API-Konsumenten standardmäßig als unsicher betrachten, unabhängig davon, ob sie extern oder intern sind. Das bedeutet, dass alle relevanten API-Sicherheitsmaßnahmen für interne und externe APIs so umgesetzt werden, als wären sie alle extern und standardmäßig nicht vertrauenswürdig.
Sicheres Fehlschlagen von APIs: Alle APIs schlagen bei der Verarbeitung von Transaktionen häufig fehl, z. B. wegen falscher Eingaben oder einer Überlastung der Anfragen. Jeder Fehler innerhalb der API-Instanz darf die Sicherheitsmechanismen nicht außer Kraft setzen und muss im Falle eines Fehlers den Zugriff verweigern.
API-Sicherheitsprobleme korrekt beheben: Sobald ein API-Sicherheitsproblem erkannt wurde, solltest du dich darauf konzentrieren, es richtig zu beheben, und "schnelle Lösungen" vermeiden, die zwar kurzfristig helfen, aber die eigentliche Ursache des Problems nicht beheben. Entwickler und API-Sicherheitsexperten müssen die Grundursache des Problems verstehen, einen Test dafür erstellen und es mit minimalen Auswirkungen auf das System beheben. Sobald das Problem behoben ist, sollte das System in allen unterstützten Umgebungen und auf allen Plattformen getestet werden. Oft entstehen API-Sicherheitsverstöße durch Fehler, die vom API-Team erkannt, aber nicht richtig behoben wurden.

Überwachung

die Qualität der Beobachtbarkeit deines API-Produkts ist wichtig. Du kannst deine API nur dann richtig verwalten, wenn du genaue und aktuelle Informationen darüber hast, wie sie funktioniert und wie sie genutzt wird. Bei der API-Überwachung geht es um die Arbeit, die du leisten musst, um diese Informationen verfügbar, zugänglich und nützlich zu machen. Im Laufe der Zeit und im großen Maßstab erweist sich die Überwachung von API-Instanzen als genauso wichtig für das API-Management wie das Design der Schnittstelle oder die Entwicklung der Implementierung - wenn du im Dunkeln tappst, kannst du nur stolpern und fallen.

Es gibt eine Menge Dinge, die in einer API-Instanz überwacht werden können:

Probleme (z. B. Fehler, Ausfälle, Warnungen und Abstürze)
Systemzustand (z. B. CPU, Speicher, I/O, Containerzustand)
API-Status (z. B. API-Betriebszeit, API-Status und insgesamt verarbeitete Nachrichten)
Nachrichtenprotokolle (z. B. Request- und Response-Nachrichtenteile, Nachrichtenkopfzeilen und Metadaten)
Nutzungsdaten (z. B. Anzahl der Anfragen, Endpunkt/Ressourcennutzung und Anfragen pro Kunde)

Mehr über Überwachung erfahren

Mit Ausnahme der API- und Nutzungsüberwachung sind die von uns beschriebenen Arten von Messungen nicht nur für API-basierte Softwarekomponenten geeignet. Wenn du nach einem guten Leitfaden für die Überwachung netzwerkbasierter Softwarekomponenten suchst, empfehlen wir dir das Buch Site Reliability Engineering von Google (O'Reilly). Es ist eine großartige Einführung in die Entwicklung von Softwaresystemen und enthält eine ziemlich umfassende Liste der Dinge, die du überwachen solltest. Eine weitere gute Quelle ist die RED-Methode von Weaveworks, die drei Kategorien von Metriken für einen Microservice identifiziert: Rate, Fehler und Dauer.

Jede dieser Gruppen von Metriken hilft deiner API auf unterschiedliche Weise. Zustands- und Problemdaten helfen dir bei der Erkennung und Behebung von Fehlern und reduzieren im Idealfall die Auswirkungen auftretender Probleme. Daten zur Nachrichtenverarbeitung helfen dir bei der Fehlersuche in der API und auf Systemebene. Nutzungsmetriken können dir helfen, dein API-Produkt zu verbessern, indem sie dir helfen zu verstehen, wie deine Nutzer/innen deine API tatsächlich nutzen. Aber zuerst musst du dir die Mühe machen, diese Daten verfügbar zu machen. Natürlich musst du auch sicherstellen, dass du eine zuverlässige Methode hast, um all diese Daten zu sammeln und sie auf eine brauchbare Weise zu präsentieren.

Je mehr Daten du produzieren kannst, desto mehr Möglichkeiten hast du, zu lernen und dein Produkt zu verbessern. Idealerweise produzierst du also einen nicht enden wollenden Strom von Daten für deine API. Die Kosten für die Datenproduktion, das Sammeln, die Speicherung und die Analyse können sich jedoch summieren, und manchmal sind diese Kosten einfach untragbar. Wenn sich zum Beispiel die Roundtrip-Zeit deiner API verdoppelt, weil sie Daten protokollieren muss, musst du einen Teil der Protokollierung einschränken oder einen besseren Weg dafür finden. Eine der wichtigsten Entscheidungen, die du treffen musst, ist die Frage, was du dir angesichts der bekannten Kosten leisten kannst zu überwachen.

Eine weitere wichtige Entscheidung ist, wie konsistent deine API-Überwachung sein soll. Wenn die Art und Weise, wie deine API Überwachungsdaten liefert, mit anderen Tools, Industriestandards oder organisatorischen Konventionen übereinstimmt, ist sie viel einfacher zu nutzen. Die Gestaltung des Überwachungssystems ist ähnlich wie die Gestaltung einer Benutzeroberfläche. Wenn deine Überwachungsschnittstelle völlig einzigartig ist, dauert es länger, bis du lernst, sie zu benutzen und Daten zu sammeln. Das ist in Ordnung, wenn du eine einzelne API hast und der einzige bist, der sie überwacht, aber wenn es um Dutzende oder Hunderte von APIs geht, musst du die Überwachungskosten senken. Wir werden diese Idee in Kapitel 7 genauer untersuchen.

Wichtige Entscheidungen zur Überwachung der Governance

Was sollte überwacht werden?: Die Entscheidung, was überwacht werden soll, ist eine große Entscheidung. Am Anfang kannst du es den einzelnen Teams überlassen, aber bei der Skalierung wirst du davon profitieren, wenn du eine einheitliche API-Überwachung hast. Konsistente Daten verbessern deine Fähigkeit, die Auswirkungen auf das System und das Systemverhalten zu beobachten. Das bedeutet, dass du einen Teil der Entscheidungsfindung zentralisieren musst.
Wie werden die Daten gesammelt, analysiert und weitergegeben?: Die Zentralisierung der Entscheidungen über die Überwachungsimplementierung erleichtert die Arbeit mit API-Daten, kann aber die Freiheit der API-Teams einschränken. Ihr müsst entscheiden, wie viel von dieser Entscheidung zentral und wie viel dezentral getroffen werden soll. Dies ist besonders wichtig, wenn es um sensible Daten geht, die geschützt werden müssen.

Entdeckung

Eine API ist nur dann wertvoll, wenn sie auch genutzt wird, aber um genutzt zu werden, muss sie erst einmal gefunden werden. Bei der Säule der API-Erkennung geht es um die Arbeit, die nötig ist, damit deine APIs für deine Zielnutzer leichter zu finden sind. Das bedeutet, dass du den Nutzern hilfst, leicht zu verstehen, was deine API macht, wie sie ihnen helfen kann, wie sie loslegen und wie sie sie aufrufen können. Die Auffindbarkeit ist eine wichtige Eigenschaft deiner API für die Entwickler. Sie erfordert ein gutes Design, eine gute Dokumentation und gute Implementierungsentscheidungen, aber du musst auch einige zusätzliche Maßnahmen ergreifen, um die Auffindbarkeit deines API-Produkts zu verbessern.

In der API-Welt gibt es zwei Hauptarten der Erkennung: die Entwurfszeit und die Laufzeit. Bei der Erkennung zur Entwurfszeit geht es darum, den API-Nutzern das Kennenlernen deines API-Produkts zu erleichtern. Dazu gehört, dass sie etwas über seine Existenz, seine Funktionen und die Anwendungsfälle, die es lösen kann, erfahren. Die Laufzeitermittlung hingegen findet statt, nachdem deine API bereitgestellt wurde. Sie hilft Software-Clients, den Netzwerkstandort deiner API anhand bestimmter Filter oder Parameter zu finden. Die Erkennung zur Entwurfszeit richtet sich an menschliche Nutzer und ist in erster Linie eine Werbe- und Marketingmaßnahme. Die Erkennung zur Laufzeit richtet sich an Maschinen-Clients und beruht auf Tools und Automatisierung. Werfen wir einen Blick auf jede dieser Methoden.

Entdeckung zur Laufzeit

Die Laufzeitermittlung ist eine Möglichkeit, die Veränderbarkeit deiner API-Landschaft zu verbessern. Wenn du über ein gutes Laufzeiterkennungssystem verfügst, kannst du den Standort deiner API-Instanzen mit nur geringen Auswirkungen auf die API-Clients ändern. Das ist besonders nützlich, wenn viele API-Instanzen gleichzeitig laufen - zum Beispiel unterstützen Microservices-Architekturen oft die Laufzeiterkennung, um das Auffinden von Diensten zu erleichtern. Die meiste Arbeit, die du dafür leisten musst, liegt in den Säulen der Entwicklung und Bereitstellung einer API.

Die Laufzeitermittlung ist ein nützliches Muster, das du kennen solltest. Es lohnt sich, es zu implementieren, wenn du ein komplexes System von APIs verwaltest. Wir werden nicht die Zeit haben, auf die Details der Implementierung einzugehen, aber es erfordert eine technologische Investition auf der Landschafts-, API- und Verbraucherebene. Wenn wir in diesem Buch von der Discovery-Säule sprechen, meinen wir in erster Linie die Discovery zur Entwurfszeit.

Entdeckung zur Entwurfszeit

Um dabei zu helfen, dass die Nutzer zur Entwurfszeit mehr über deine API erfahren, musst du sicherstellen, dass du die richtige Art von API-Dokumentation zur Verfügung hast. Die Dokumentation darüber, was deine API tut und welche Probleme sie löst, sollte für Nutzer/innen, die danach suchen, leicht zugänglich sein. Diese Art von "Produktmarketing" ist ein wichtiger Teil der Entdeckung, aber es ist nicht das Einzige, was zählt. Es ist nicht das Einzige, worauf es ankommt. Ein wichtiger Teil dieser Säule ist es, deinen Nutzern zu helfen, die Informationen überhaupt zu finden. Um erfolgreich zu sein, musst du dich mit deiner Nutzergemeinschaft auseinandersetzen und sie ansprechen. Wie du das machst, hängt stark vom Kontext deiner Nutzerbasis ab:

Externe APIs

Wenn deine API hauptsächlich von Menschen genutzt wird, die nicht in deiner Gruppe oder Organisation arbeiten, musst du in die Vermittlung deiner Botschaft an sie investieren. Das bedeutet, dass du dein API-Produkt genauso vermarkten musst, wie du eine Software vermarkten würdest: Suchmaschinenoptimierung, Sponsoring von Veranstaltungen, Engagement in der Gemeinschaft und Werbung. Dein Ziel ist es, sicherzustellen, dass alle potenziellen Nutzer deines APIs verstehen, wie dein Produkt ihnen helfen kann, ihre Bedürfnisse zu erfüllen. Welche Marketingmaßnahmen du im Einzelnen ergreifst, hängt natürlich stark von deinem Kontext, der Art der API und den Nutzern ab, die du ansprechen willst.

Wenn du zum Beispiel ein SMS-API-Produkt entwickelst und um Entwickler-Nutzer konkurrierst, dann wirst du an den Orten werben, an denen du deine potenziellen Nutzer erwartest: Webentwickler-Konferenzen, Blogs über Zwei-Faktor-Authentifizierung und Telekommunikationskonferenzen. Wenn du dich an unabhängige Entwickler/innen wendest, könntest du dich auf digitale Werbung verlassen, aber wenn du auf große Unternehmen abzielst, könntest du in ein Team von Vertriebsmitarbeiter/innen und deren Beziehungsnetzwerk investieren. Wenn du in einem überfüllten Markt konkurrierst, musst du wahrscheinlich viel Aufwand betreiben, um dich von der Konkurrenz abzuheben, aber wenn dein Produkt einzigartig ist, brauchst du vielleicht nur ein bisschen Suchmaschinenoptimierung, um die Leute in die Tür zu bekommen. Wenn es um Produktmarketing geht, ist der Kontext entscheidend.

Interne APIs

Wenn deine API von deinen eigenen Entwicklern genutzt wird, hast du wahrscheinlich ein festes Publikum. Das bedeutet aber nicht, dass du die Auffindbarkeit deiner API ignorieren kannst. Eine interne API muss entdeckt werden, um genutzt werden zu können, und wenn sie zu schwer zu finden ist, wirst du mit der Zeit Probleme bekommen. Wenn die internen Entwickler sie nicht kennen, können sie sie nicht nutzen und verschwenden vielleicht sogar Zeit damit, eine andere API zu entwickeln, die dasselbe tut wie deine. Ein wettbewerbsfähiger Markt von APIs ist normalerweise ein gutes Zeichen, und Wiederverwendbarkeit wird in Unternehmen oft überbewertet. Wenn aber Leute in deinem Unternehmen perfekt funktionierende APIs duplizieren, nur weil sie sie nicht kennen, ist das eine Belastung für deine Ressourcen.

Interne APIs können auf die gleiche Weise vermarktet werden wie externe APIs. Nur das Marketing-Ökosystem ist anders. Während du dich bei einer externen API wahrscheinlich an die Google-Suchmaschine wendest, musst du bei einer internen API vielleicht nur in die unternehmenseigene Tabelle kommen, in der die APIs des Unternehmens aufgelistet sind. Für eine externe API kann es sinnvoll sein, eine Entwicklerkonferenz zu sponsern, aber für eine interne API ist es vielleicht besser, einfach alle Entwicklerteams im Unternehmen zu besuchen und sie über deine API zu informieren.

Eine große Herausforderung bei der Vermarktung interner APIs ist oft der Mangel an Reife und Standardisierung in der Organisation. Wenn du deine APIs in einem großen Unternehmen vermarktest, ist die Wahrscheinlichkeit sehr groß, dass es mehr als eine API-Liste gibt, die im Umlauf ist. Um gute Arbeit zu leisten, musst du sicherstellen, dass deine API auf allen wichtigen Listen und Registern steht. Ebenso kann es in der Praxis schwierig sein, alle Entwicklungsteams in deinem Unternehmen kennenzulernen und Zeit mit ihnen zu verbringen, aber wenn die Nutzung deiner API für dich wichtig ist, lohnt sich die Investition.

Wichtige Entscheidungen für die Discovery Governance

Wie wird das Entdeckungserlebnis aussehen?: Du musst ein gutes Entdeckungserlebnis für die Nutzer deiner API entwickeln. Das bedeutet, dass du dich für Entdeckungstools, Benutzererfahrung und eine Zielgruppe entscheiden musst. Bei der Skalierung musst du auch entscheiden, wie konsistent diese Erfahrung sein soll - wenn du eine hohe Konsistenz brauchst, musst du die Designentscheidungen vielleicht zentralisieren.
Wann und wie werden APIs beworben?: Die Vermarktung einer API kostet Zeit und Mühe, also musst du entscheiden, wer entscheiden soll, wann eine API vermarktet wird. Du kannst es den einzelnen API-Teams überlassen oder diese Entscheidung zentral treffen. Wenn du die Entscheidung an deine Teams weitergibst, musst du sicherstellen, dass zentralisierte Erkundungstools und -prozesse die Teams nicht an ihren Erkundungszielen hindern.
Wie wird die Qualität des Entdeckungserlebnisses aufrechterhalten?: Im Laufe der Zeit, wenn sich die APIs ändern, werden die Informationen in jedem Discovery-System ungenauer. Wer sorgt dafür, dass das Discovery-System genau ist? Wer sorgt dafür, dass das Nutzererlebnis im Laufe der Zeit nicht abnimmt?

Change Management

Wenn du deine API nie ändern müsstest, wäre es ziemlich einfach, eine API zu verwalten. Aber APIs müssen repariert, aktualisiert und verbessert werden, und du musst immer bereit sein, deine API zu ändern. Die Säule des Änderungsmanagements umfasst alle Planungs- und Managemententscheidungen, die du im Umgang mit Veränderungen treffen musst. Es ist ein äußerst wichtiger und komplexer Bereich - und genau darum geht es in diesem Buch.

Im Allgemeinen gibt es drei Ziele für das Veränderungsmanagement:

Die Auswahl der besten Änderungen
Diese Änderungen so schnell wie möglich umsetzen
Diese Änderungen vornehmen, ohne etwas kaputt zu machen

Die Auswahl der besten Änderungen bedeutet, dass du Änderungen vornimmst, die die strategischen Ziele deiner API unterstützen. Das bedeutet aber auch, dass du lernen musst, Prioritäten zu setzen und Änderungen auf der Grundlage von Kosten, Kontexten und Beschränkungen zu planen. Das ist die eigentliche Aufgabe der Produktverwaltung und einer der Gründe, warum wir im vorherigen Kapitel das Konzept der API als Produkt eingeführt haben. Wenn du dir klare strategische Ziele setzt und deine Zielgruppe identifizierst, kannst du besser entscheiden, welche Änderungen am sinnvollsten sind. Je mehr du über die Arbeit in jeder der anderen neun Säulen erfährst, desto besser kannst du die Kosten einschätzen. Mit guten Informationen über Kosten und Nutzen kannst du intelligente Produktentscheidungen für deine API treffen.

Das Gleichgewicht zwischen der Sicherheit und der Geschwindigkeit von Änderungen ist schwierig, aber genau das musst du tun. Jede der Entscheidungen, die du in den Säulen eines API-Produkts triffst, wirkt sich auf die Geschwindigkeit oder die Sicherheit von Änderungen aus. Die Kunst besteht darin, Entscheidungen zu treffen, die das eine maximieren und das andere so wenig wie möglich beeinträchtigen. In den Kapiteln 5, 7 und 8 werden wir diese Idee aus der Perspektive der Veränderungskosten, der Veränderungen im Laufe der Zeit und des Einflusses von Organisationen und der Kultur auf die Veränderung weiter untersuchen. In den letzten Kapiteln dieses Buches führen wir dann eine zusätzliche Komplexität ein: den Umfang. In den Kapiteln 9, 10 und 11 geht es um das Änderungsmanagement für eine ganze Landschaft von APIs statt nur einer.

Die Umsetzung von Änderungen ist nur die Hälfte der Arbeit des Veränderungsmanagements. Die andere Hälfte besteht darin, den Leuten mitzuteilen, dass sie mehr zu tun haben, weil du etwas geändert hast. Wenn du zum Beispiel ein Schnittstellenmodell änderst, musst du wahrscheinlich deine Designer, Entwickler und Betriebsteams darüber informieren, dass neue Arbeit auf sie zukommt. Je nach Art der Änderung musst du wahrscheinlich auch deine Nutzer/innen darüber informieren, dass sie ihre Client-Software aktualisieren müssen. In der Regel machst du das, indem du deine API versionierst. Wie du die Versionierung vornimmst, hängt stark von der Art deiner API und den Protokollen, Formaten und Technologien ab, die du verwendest; mehr dazu im Abschnitt "Versionierung".

Wichtige Entscheidungen für die Steuerung des Veränderungsmanagements

Welche Freisetzungen müssen schnell sein und welche müssen sicher sein?: Eine wichtige Governance-Entscheidung ist, wie verschiedene Arten von Änderungen behandelt werden sollen. Wenn du diese Entscheidung zentralisierst, kannst du eine einheitliche Regelung schaffen, die je nach Auswirkung unterschiedliche Freigabeprozesse zulässt. Manche nennen diesen Ansatz "bimodal" oder "zwei Geschwindigkeiten", aber wir glauben, dass es in einer komplexen Organisation mehr als zwei Geschwindigkeiten gibt. Du kannst diese Entscheidung auch dezentralisieren und einzelne Teams die Auswirkungen selbst beurteilen lassen. Die Gefahr dabei ist, dass deine Teams nicht in der Lage sind, die Auswirkungen auf das System richtig einzuschätzen, also musst du dafür sorgen, dass deine Systemarchitektur belastbar ist.

Die Säulen gemeinsam nutzen

Die Säulen, die wir in diesem Kapitel definiert haben, katalogisieren ein enormes Ausmaß an Entscheidungen und Anstrengungen. Aber wir haben sie nicht nummeriert, nach Prioritäten geordnet oder in eine Reihenfolge gebracht, und das ist Absicht. Die Methoden der Projekt- und Produktabwicklung unterscheiden sich von Unternehmen zu Unternehmen erheblich. Deshalb wollten wir dir eine strukturierte Methode an die Hand geben, mit der du die wichtigsten Entscheidungen und Aufgaben, die du zu erledigen hast, so definieren kannst, dass sie für jede Softwareentwicklungsmethode, die du verwendest, nützlich sind.

Eines der Probleme bei der Aufteilung von Entscheidungen und Arbeit in Säulen ist jedoch, dass sie sich wie unterschiedliche und unabhängige Kategorien von Arbeit anfühlen können. In der Praxis ist das aber fast nie der Fall. In diesem Abschnitt werden wir einige der häufigsten Möglichkeiten erkunden, wie die API-Säulen gemeinsam genutzt werden können, um die Ziele der API-Produktentwicklung zu erreichen. Wir sehen uns an, wie sich die einzelnen Säulen gegenseitig beeinflussen und welche ganzheitliche Perspektive du einnehmen musst, wenn du sie einsetzt. Später, in Kapitel 7, werden wir uns ansehen, wie sich die Investitionen in die einzelnen Säulen im Laufe der Lebensdauer einer API verändern.

Werfen wir zunächst einen Blick darauf, wie die API-Säulen zusammen verwendet werden, um die Herausforderungen bei der Planung und Gestaltung einer API zu meistern.

Anwendung der Säulen bei der Durchführung der Planung

In den letzten Jahren haben die Phasen der Planung und des Designs einen schlechten Ruf bekommen. Viele Umsetzer/innen befürchten, in die Falle des "Big Design Up Front" (BDUF) zu tappen, bei dem ein Team unverhältnismäßig viel Zeit in der Planungsphase verbringt, völlig losgelöst von den praktischen Realitäten der Umsetzung. Mit der zunehmenden Verbreitung von Agilen Prinzipien, Scrum-Methoden und Kanban-Management in unserer Branche liegt der Schwerpunkt verstärkt auf dem "Tun" und dem Testen und Lernen. Wir halten das für eine gute Sache.

Wir wissen aber auch, dass ein klares Ziel, eine kohärente Strategie und ein klarer Plan, der die Umsetzung vorantreibt, von großem Wert sind. Die Notwendigkeit von Planung und Design ist bei einem API-Produkt besonders wichtig. Das liegt daran, dass Änderungen an einer Schnittstelle immer mit Kosten verbunden sind. Wir alle kennen die Frustration, wenn wir etwas neu lernen müssen, wenn eine Anwendung ihre Benutzeroberfläche ändert. Änderungen an APIs können besonders kostspielig sein, denn sie können sich leicht auf den Code eines anderen Unternehmens oder sogar auf dessen gesamtes Geschäftsmodell auswirken.

Deshalb lohnt es sich, unabhängig von deiner Bereitstellungsmethodik, mit einem klaren Plan für deine API zu beginnen. Unserer Erfahrung nach können selbst stark agil ausgerichtete API-Teams von einer gewissen Planung im Vorfeld profitieren. Bei API-Produkten ist es wichtig, in die richtige Richtung zu starten und die Arbeit in den verschiedenen Säulen darauf auszurichten. Wir haben insbesondere drei Bereiche identifiziert, auf die wir uns konzentrieren müssen: Designausrichtung, Prototyping und Definition der Grenzen.

Teste deine Strategie und Designausrichtung

Wie bereits im Abschnitt "Design" erwähnt , ist es wichtig, dass du deine Strategie und dein Design aufeinander abstimmst. Um eine API zum Leben zu erwecken, müssen in den Bereichen Design ("Design") und Entwicklung ("Entwicklung") unglaublich viele Entscheidungen getroffen werden. Wir haben erlebt, dass viele Praktiker/innen Schwierigkeiten haben, wenn sie kein klar definiertes Ziel haben, auf das sie hinarbeiten.

Um deine Ausrichtung zu verbessern, ist es wichtig, dass du dein Design ständig mit deiner Strategie abgleichst. Wenn du Entscheidungen zur Gestaltung und Umsetzung triffst, kann es leicht passieren, dass du die strategische Perspektive deiner Arbeit verlierst. Du musst deine Entscheidungen mit deinen strategischen Zielen abgleichen und neu kalibrieren. Wenn du es geschafft hast, KPIs oder OKRs zu definieren, wird es viel einfacher sein, deine Entscheidungen zu überprüfen.

Zwei Strategien im Vergleich: Twitter und Slack

Ein Vergleich der Kommunikationsanwendungen Twitter und Slack ( ) macht deutlich, wie sich die Entscheidungen, die wir in der Strategie treffen, auf alle Entscheidungen in den anderen Säulen auswirken können. In "A Tale of 2 API Platforms" betont Jason Costa die Auswirkungen, die eine strategische Ausrichtung (oder das Fehlen einer solchen) auf die Entwicklung eines API-Produkts haben kann. Er hebt besonders hervor, wie Slack zielgerichtete Entscheidungen in Bezug auf Design, Entwicklung und Änderungsmanagement getroffen hat, um seine strategischen Ziele zu erreichen.¹ Er vergleicht diesen Ansatz mit der eher organischen, unbeständigen strategischen Ausrichtung von Twitter, die laut Costa zu einem möglicherweise nicht wieder gutzumachenden Zerwürfnis mit den Entwicklern geführt hat, die ihre APIs genutzt haben.

Seine Fallstudie verdeutlicht eine wichtige Überlegung für jeden API-Entwickler: Die Entscheidungen, die wir innerhalb einer strategischen Säule treffen, haben wahrscheinlich einen weltbewegenden Einfluss auf alle anderen Säulen, in denen wir arbeiten.

Prototyp früh

Moderne Softwareentwicklungsmethoden betonen die Wichtigkeit von Iterationen, Sprints und kleineren Änderungspaketen. Unserer Erfahrung nach ist dies ein wesentliches Element, um mit einem API-Produkt erfolgreich zu sein. Wann immer möglich, solltest du deine Strategie so schnell wie möglich umsetzen, damit du ihre Umsetzbarkeit testen kannst. Das bedeutet, dass du bereits während der Ausarbeitung deiner Strategie entwicklungs- und testübergreifende Arbeiten ("Entwicklung") durchführst.

Es gibt viele Namen für diese Art von Test- und Lernaktivitäten: Proof of Concepts, Piloten, "Stahlfäden", MVPs usw. Wie auch immer du es nennst, der Wert der frühen Umsetzung ist immens. Die Idee der kontinuierlichen Verbesserung zieht sich wie ein roter Faden durch dieses Buch.

API Prototyping Tools

Vor Jahren bedeutete das Prototyping einer API, einen Ingenieur zu engagieren, der eigenen Code schreibt. Doch heute gibt es eine Vielzahl von Tools, die dabei helfen können. Dazu gehören Frameworks wie Spring Boot, die die in "Entwicklung" beschriebene Arbeit beschleunigen und es den Teams ermöglichen, schnell testbare API-Prototypen zu erstellen. Teams können auch Tools für das Oberflächendesign verwenden, um die Dokumentation ("Dokumentation") schnell zum Leben zu erwecken. Es gibt ein wachsendes Ökosystem von webbasierten und IDE-Plug-ins, mit denen du schnell eine API-Spezifikation erstellen kannst. Mit einigen Tools können Teams sogar schnell APIs aus einem bestehenden Datensatz oder einer Datenbank erstellen. Wir empfehlen dir, ein Tool zu finden, das dir hilft, dich so früh wie möglich in der Entwurfs- und Planungsphase auf die Design- und Nutzungsaspekte deiner API zu konzentrieren.

Grenzen festlegen

In der Praxis kann dein API-Produkt tatsächlich aus einer Sammlung einzelner Komponenten bestehen. Das zeigt sich vor allem in der "Microservice"-Architektur, die für API-Implementierungen immer beliebter geworden ist. Daher wird es immer wichtiger, die Grenzen für die Komponenten frühzeitig zu planen, damit du deine API-Produktstrategie umsetzen kannst.

In der Praxis bedeutet das, dass ein Teil deiner Designarbeit für eine einzelne API darin besteht, zu definieren, wie diese API in mehrere Teile aufgeteilt werden kann. Der schwierige Teil dabei ist, die richtigen Grenzen für deine Komponenten zu definieren. Immer mehr Teams legen die Grenzen frühzeitig fest, damit sie Komponenten entwickeln können, die besser auf ihre Strategie abgestimmt sind.

Die Säulen für die Schöpfung nutzen

Um die API-Strategie zum Leben zu erwecken, müssen wir das API-Produkt implementieren. In Kapitel 7 werden wir untersuchen, was es bedeutet, ein API-Produkt aus der Perspektive des Lebenszyklus zu realisieren. Doch bevor wir das tun, sollten wir uns überlegen, wie die eigentliche Arbeit erledigt werden soll. Bisher haben wir vier Säulen vorgestellt, die bei der Erstellung einer API wirklich wichtig sind: Design, Dokumentation, Entwicklung und Tests. Jetzt müssen wir herausfinden, wie du diese Säulen sinnvoll zusammen nutzen kannst.

Wenn du Erfahrung in der Softwareentwicklung hast, wirst du wissen, dass die Säulen, die wir für den Aufbau einer API definiert haben, nicht wirklich neu oder neuartig sind. Jede Software, die wir heutzutage schreiben - egal ob API oder nicht - durchläuft die klassischen Phasen des Entwerfens, Entwickelns, Dokumentierens und Testens. Es gibt auch viele Softwareentwicklungsmethoden, die du einsetzen kannst, um die Arbeit in diesen Phasen zu verwalten. Auf findest du zum Beispiel Kanban, Scrum und das Scaled Agile Framework, die sich alle bei Praktikern großer Beliebtheit erfreuen, um die agilen Prinzipien auf die Produktentwicklung anzuwenden. Wir sind sicher, dass dein Unternehmen über eine etablierte Methode zur Softwareentwicklung verfügt und dass du diese auf deine Arbeit in der API-Entwicklung anwenden kannst.

Das Besondere an der Erstellung von APIs ist jedoch, dass sie viele verschiedene Konzepte in einem einzigen Produkt kapseln. Wir haben dies bereits zu Beginn des Buches angesprochen, als wir die Herausforderung des Verständnisses von Schnittstellen, Implementierung und Instanzen ("Schnittstelle, Implementierung und Instanz") beschrieben haben. Du musst herausfinden, wie du die kreativen Säulen der API-Arbeit so anwendest, dass diese Teile zusammengeführt werden. Wie entwirfst, entwickelst, dokumentierst und prüfst du eine API so, dass die Schnittstelle und die Implementierung den größten strategischen Nutzen bringen?

Leider gibt es kein Patentrezept, um diesen Wert zu erschließen. Aber die gute Nachricht ist, dass wir drei Ansätze herausgefunden haben, mit denen Praktiker erfolgreich sind: "Dokumentation zuerst", "Code zuerst" und "Test zuerst". Werfen wir einen Blick auf jeden dieser Ansätze und erfahren wir, wann sie am sinnvollsten sind.

Dokumentation-zuerst

Wenn wir uns mit den technischen Aspekten von APIs befassen, konzentrieren wir uns oft auf ihre technischen Elemente: den Code und die Konfiguration, die das Laufzeitverhalten steuern. Aber nichts von dem, was zur Laufzeit passiert, geschieht ohne einen menschlichen Entwickler, der am Client-Code arbeitet, der die API nutzt. Deshalb verfolgen manche Teams bei ihrer API-Ausführungsmethode einen "dokumentationsorientierten" Ansatz.

Dokumentation zuerst bedeutet, dass das Team der Gestaltung der menschlichen Schnittstelle der API - der Dokumentation - Priorität einräumt. Anstatt sich zuerst Gedanken über die technische Umsetzung in Go, Java, NodeJS oder einer anderen Sprache zu machen, konzentriert sich das Team darauf, die API zu dokumentieren, bevor sie existiert. Wenn wir zum Beispiel eine Zahlungs-API entwickeln, können wir damit beginnen, die Entscheidungen und Arbeiten in der Dokumentation ("Dokumentation") umzusetzen, bevor wir Code schreiben.

Ein Vorteil dieser Vorgehensweise ist, dass wir die menschliche Schnittstelle der API testen können, bevor wir in die damit verbundene Implementierungsarbeit investieren. Wenn wir zum Beispiel einen Leitfaden für die Nutzung und Beispiele für unsere neue Zahlungs-API schreiben, können wir ihn mit einer Gruppe potenzieller Entwickler testen. Es ist viel einfacher, die Dokumentation auf der Grundlage ihres Feedbacks zu ändern, als eine API-Implementierung zu ändern.

Aber "Dokumentation zuerst" bedeutet nicht, dass es nur um die Dokumentation geht. In der Praxis ist es sinnvoll, mit den Aktivitäten "Entwicklung" und "Testen" zu beginnen, während die Spezifikation fertiggestellt wird. Du kannst noch einen Schritt weiter gehen, indem du Prototypen oder "Mocks" der dokumentierten API entwickelst, damit du ein lebendes, aufrufbares Produkt für frühe Tests anbieten kannst.

Der Schlüssel zum dokumentationsorientierten Ansatz liegt darin, dass wir unsere Implementierungsentscheidungen an der Erlernbarkeit, Nutzbarkeit und Verständlichkeit der API ausrichten. Das ist eine gute Methode, wenn du sicherstellen willst, dass dein Team den Entwickler in der Entwicklungsphase an die erste Stelle setzt. Es ist auch eine gute Möglichkeit, nicht-technischen Stakeholdern und Sponsoren frühe Ergebnisse und Assets zur Verfügung zu stellen.

Eine der Herausforderungen des dokumentationsorientierten Ansatzes ist, dass er zu Produkten führen kann, die zu viel versprechen und zu wenig halten. Du musst sicherstellen, dass die Schnittstellen, die auf dem Papier dokumentiert sind, von den Ingenieurteams, die sie bauen müssen, auch umgesetzt werden können. In manchen Fällen baust du auf einem komplexen Satz von nachgelagerten Funktionen auf, die nicht geändert werden können. Wenn sich der angestrebte Zielzustand, der dokumentiert ist, erheblich von der Realität des Implementierers unterscheidet, können die Kosten für die Erstellung der API überwältigend sein.

Code-first

Der code-first-Ansatz konzentriert sich zuerst auf die Komplexität der Implementierung der API-Interna. Das bedeutet, dass das Team den Aktivitäten "Entwicklung" und "Testen" Priorität einräumt, damit es schnell und effizient eine erste Version eines API-Produkts liefern kann. Das bedeutet nicht, dass das Team keine API-Dokumentation erstellt, aber es bedeutet, dass sich das dokumentierte Design an die Entscheidungen hält, die während der Implementierung getroffen wurden, und nicht umgekehrt.

Der Code-first-Ansatz ist am sinnvollsten, wenn die Geschwindigkeit der Veröffentlichung schwerer wiegt als die Nutzbarkeit und Verwendbarkeit der API. Teams, die Microservices entwickeln, geben der Entwicklungsarbeit oft den Vorrang, weil sie nicht vorhaben, ihren Microservice mit anderen Teams zu teilen. In diesem Fall liegt der Schwerpunkt eher darauf, dass der Code leicht zu ändern und zu veröffentlichen ist, als auf der Nutzung.

Dieser Ansatz kann auch nützlich sein, um die Umsetzbarkeit eines API-Produkts als "Proof of Concept" oder "Technology Spike" schnell zu erforschen und zu testen, um zu prüfen, ob alle risikoreichen Elemente identifiziert oder entschärft wurden. Ein API-Team kann zum Beispiel in einem ersten Schritt mit dem Schreiben von Code für eine Hypermedia- oder GraphQL-API beginnen, weil es mit diesem speziellen API-Stil nicht vertraut ist und die praktischen Aspekte des Designs bewerten muss.

Code-first-Teams können (und sollten) trotzdem eine Dokumentation für ihre Schnittstelle erstellen. Je nach Art des Projekts kann diese Dokumentation weniger umfangreich ausfallen als bei einem dokumentationsorientierten Team. Code-First-Teams zum Beispiel dokumentieren ihre APIs in der Regel mit maschinenlesbaren API-Beschreibungssprachen wie OpenAPI, anstatt menschenlesbare Anleitungen zu erstellen. In manchen Extremfällen behauptet das Team, dass der Code die Dokumentation ist. Der wichtigste Aspekt des Code-First-Ansatzes ist jedoch, dass sich die Dokumentationsarbeit ausschließlich auf die Vermittlung von Designentscheidungen konzentriert, die während der Codierungsphase getroffen wurden.

Wie zu erwarten, kann ein Code-first-Ansatz leicht technische und Implementierungsaspekte in das Oberflächendesign projizieren. Um eine Code-first-API für Außenstehende leichter nutzbar zu machen, sind oft Änderungen am Code oder die Erstellung einer weiteren API erforderlich, die darauf aufbaut. Es ist wichtig anzumerken, dass dieser Ansatz langfristig nur schwer durchzuhalten ist, wenn du über dein unmittelbares Team oder deine Organisation hinausgehst und in einer kontrollierten Umgebung arbeitest.

Test-first

Eine moderne Variante des code-first und documentation-first Ansatzes ist die test-first Implementierung. Bei dieser Art der API-Entwicklung hat die Testbarkeit der API Vorrang vor ihrer Dokumentierbarkeit oder Implementierbarkeit. Diese ist eine Anwendung von Test-Driven Development (TDD) auf den API-Bereich.

Ein testorientierter Ansatz bedeutet, dass das API-Team zunächst Testfälle erstellt, die einem gewünschten Zielzustand entsprechen, und dann die Arbeit der Implementierung übernimmt, damit der Testfall erfolgreich ist. Für die Entwicklung (siehe "Entwicklung") bedeutet das normalerweise, dass wir Tests schreiben, die die API aufrufen, bevor die API geschrieben wird. Bei der Entwicklung einer Zahlungsverkehrs-API würden wir zum Beispiel einen Testfall schreiben, um eine Zahlung über eine HTTP-Anfrage durchzuführen, bevor wir den Code für die Bearbeitung und Ausführung der Anfrage schreiben.

Die Dinge werden noch interessanter, wenn wir die Säule der Dokumentation betrachten (siehe "Dokumentation"). Ein testgetriebener Entwicklungsansatz bedeutet zumindest, dass die Dokumentation die Testfälle widerspiegeln sollte, die wir entwickeln. Die Erstellung von Testfällen ist praktisch die Designaktivität für die Schnittstelle. Einige Teams gehen noch einen Schritt weiter und experimentieren mit der automatischen Generierung von Dokumentation und Codebeispielen auf der Grundlage der Testfälle, die geschrieben werden.

Mit Tests zu beginnen ist eine fantastische Möglichkeit, die Testbarkeit eines API-Produkts zu verbessern. Dies führt zu sichereren und vorhersehbareren zukünftigen Änderungen, weil das Team Vertrauen in seine Fähigkeit hat, seine Ergebnisse zu testen. Allerdings ist die Testphase mit zusätzlichen Entwicklungskosten verbunden und kann die Zeit bis zur ersten Veröffentlichung verlängern. In der Praxis verfolgen viele Teams einen dokumentationsorientierten Ansatz für ihr API-Produkt und einen testgetriebenen Ansatz für die Entwicklung.

Die Säulen für Betrieb und Verwaltung nutzen

In den letzten zwei Jahrzehnten hat der Druck zugenommen, Software zu entwickeln, die schnell geliefert und geändert werden kann und trotzdem stabil, sicher und zuverlässig funktioniert. Dies hat zu Veränderungen in der Art und Weise geführt, wie Software entwickelt und betrieben wird. Unternehmen setzen zunehmend auf DevOps-Kulturen, Site Reliability Engineering und einen DevSecOps-Ansatz, der die Sicherheit in den Entwicklungsprozess einbindet.

Ops nach links verschieben

Vor Jahren war es üblich, dass Entwickler/innen eine Anwendung schrieben und sie dann an ein Betriebsteam übergaben, damit dieses sie betreiben und unterstützen konnte. Aber heute gibt es ein wachsendes Interesse daran, Anwendungen anders zu entwickeln. Teams, die eine DevOps-Kultur verkörpern, bringen die Welten der Entwicklung und des Betriebs zusammen, damit die Anwendungen von Anfang an betriebsfähig sind. In vielen modernen Entwicklungsteams ist der Betrieb zu einem Bürger erster Klasse im Entwicklungsprozess geworden und nicht nur ein nachträglicher Gedanke.

Die Anwendung dieses Ansatzes auf die API-Entwicklung bedeutet, dass die Säulen Design, Entwicklung, Testen, Einsatz und Überwachung aufeinander abgestimmt werden müssen. In der Praxis bedeutet dies, dass die Teams die Entscheidungsfindung und die Arbeit, die sowohl in der kreativen als auch in der operativen Säule stattfindet, teilen müssen. Ein API-Team, das Entscheidungen über Tools und Frameworks trifft, muss sowohl die Belange der Codeerstellung als auch die Belange der Bereitstellung und des Betriebs berücksichtigen.

In der Praxis implementieren die meisten Unternehmen eine Plattform von DevOps-Automatisierungstools, die die Bedürfnisse der API-Entwicklungsteams erfüllen. Das Ziel dieser Tools ist es, die Zeit für die Erstellung und Änderung von APIs zu verkürzen und gleichzeitig ihre Funktionsfähigkeit zu verbessern. Diese Tools ermöglichen in der Regel die Standardisierung und Automatisierung von Test-, Bereitstellungs- und Überwachungsaufgaben.

Zum Beispiel könnte ein Unternehmen zum Zeitpunkt der Erstellung dieses Artikels eine DevOps-Plattform mit den folgenden Tools einführen:

CI/CD-Pipelines: Ein Continuous Improvement (CI) und Continuous Delivery² (CD) Werkzeug automatisiert den Prozess des Testens und der Bereitstellung einer Softwarekomponente. Im API-Bereich werden CI/CD-Pipelines oft so konfiguriert, dass sie prüfen, ob eine API keine bahnbrechenden Änderungen einführt, bevor sie in der Produktionsumgebung eingesetzt wird. Diese Art der Test- und Bereitstellungsautomatisierung kann auf alle Bestandteile deines API-Produkts angewandt werden, einschließlich Design-Assets, Dokumentation und Implementierungen.
Containerisierung: Heutzutage werden APIs oft in Form von Containern implementiert, die als in sich geschlossene Einsatzeinheiten betrieben werden können. Die Einführung der Containerisierung kann die Art und Weise, wie APIs implementiert werden, grundlegend verändern. Viele Unternehmen, die mit der Containerisierung ihrer APIs beginnen, führen schließlich einen "Microservices"-Ansatz ein, bei dem sie ein API-Produkt in kleinere, unabhängig voneinander einsetzbare Teile aufteilen.
Tools zur Beobachtbarkeit: Um bei der Überwachung und Fehlerbehebung zu unterstützen, implementieren DevOps-Teams zunehmend Tools, die bei der Aggregation, Visualisierung und Integration von Protokoll- und Überwachungsdaten helfen. Für API-Teams bedeutet dies, dass die Design- und Entwicklungsarbeit an standardisierten Schnittstellen und Formaten ausgerichtet sein muss, die von DevOps-Teams festgelegt werden. Ein Sonderfall bei API-Produkten ist, dass Beobachtungswerkzeuge oft auf externe Nutzer einer API ausgeweitet werden. Zum Beispiel kann ein Entwicklerportal Dritten, die die API-Produkte eines Unternehmens nutzen, Analysen zur Nutzung und Fehlerbehebung anbieten.

Sicherheit nach links verlagern

Wie bereits in der Säule Sicherheit erwähnt hat, bieten APIs eine besondere Angriffsfläche für potenzielle Angreifer. API-Implementierer müssen insbesondere die Bedrohungsabwehr in den Bereichen Dokumentationsportale, Schnittstellendesign, Datenspeicherung und Code-Implementierung berücksichtigen. In den letzten Jahren haben sich drei Sicherheitsmuster herausgebildet, die die Art und Weise, wie im API-Bereich gearbeitet wird, verändern:

DevSecOps Automatisierung: Unter hat die Art und Weise, wie Ops-fokussierte Werkzeuge die Entwicklung von APIs beeinflusst haben, den gleichen Effekt wie sicherheitsorientierte Werkzeuge. Unternehmen integrieren zunehmend Schwachstellen-Scanner in ihre CI/CD-Pipelines, damit alle Änderungen schnell und effizient geprüft werden, bevor sie in die Produktion übernommen werden. Viele API-Teams in Unternehmen verwenden zum Beispiel Scanner, die API-Implementierungen auf OWASP-Bedrohungen prüfen. Indem diese Schwachstellenprüfung Teil des Programmierprozesses ist, wird sichergestellt, dass die Teams Sicherheitsschwachstellen frühzeitig im Entwicklungsprozess beheben.
Automatisierte Erkennung von Bedrohungen: Heutzutage überprüfen Organisationen nicht nur passiv den Code, wenn Scanner ausgelöst werden, sondern scannen auch aktiv die Assets, um Schwachstellen und Probleme zu finden. Inzwischen gibt es ein gesundes Ökosystem von Tools, die Teams bei der kontinuierlichen Überwachung von Protokollen, Code-Repositories, Datenbanken und sogar Live-APIs unterstützen. Diese Art der kontinuierlichen Überwachung von Bedrohungen trägt dazu bei, das Verhalten von API-Teams so zu verändern, dass Sicherheitsbedenken bereits in einem frühen Stadium des Entwicklungsprozesses berücksichtigt werden.
Zero-Trust-Sicherheitsmodelle: Vor Jahren beruhten die meisten Sicherheitsmodelle auf der Schaffung eines sicheren Perimeters, so dass den Systemen innerhalb des Perimeters vertraut werden konnte. In den letzten Jahren hat Google jedoch dazu beigetragen, ein "Zero-Trust"-Modell zu verbreiten, bei dem keinem System allein aufgrund seines Standorts vertraut werden sollte. Dieser Wandel ist eine Folge der zunehmend dezentralisierten Organisations- und Bereitstellungsmodelle, die mit der modernen Softwareentwicklung einhergehen. Für API-Teams bedeutet "Zero-Trust", dass API-Ersteller/innen im Rahmen ihrer Design- und Entwicklungsarbeit überlegen müssen, wie die Zugriffskontrollen durchgesetzt werden sollen.

Laufzeitplattformen

Die Einführung der Betriebs- und Sicherheitsarbeit über die Säulen Design, Entwicklung und Testen hinweg ist mit Kosten verbunden. Teams, die sich bisher auf das Schreiben von Code konzentriert haben, müssen sich nun mit den Details von Betriebssystemen, Infrastruktur und Sicherheit auseinandersetzen. Neue Tools und Plattformen tragen jedoch dazu bei, einige dieser Kosten zu senken.

API-Teams werden immer abhängiger von den Laufzeitplattformen, auf denen ihre Software laufen wird. Das liegt daran, dass moderne Plattformen einen großen Teil der Komplexität bewältigen können, die sich aus der Anwendung von Operate- und Run-Säulen ergibt. Die spezifischen Tools, Technologien und Plattformen, die die Menschen nutzen, ändern sich ständig, aber zum Zeitpunkt der Erstellung dieses Artikels haben drei Technologien einen großen Einfluss: Kubernetes, Services Meshes und Serverless.

Kubernetes

Die Standardisierung von als Bereitstellungseinheit (z. B. als "shippable" Container) hat vielen Teams geholfen, den Betrieb und die Ausführung ihrer APIs zu verbessern. Aber der sichere und stabile Betrieb eines Containers in einer Produktionsumgebung erfordert immer noch eine sorgfältige Planung und Verwaltung. Deshalb setzen viele Teams auf die Container-Orchestrationsplattform Kubernetes. Kubernetes bietet eine standardisierte Methode zur Bereitstellung, Skalierung, Ausführung und Überwachung von Container-Workloads. Das ist attraktiv, denn es bedeutet, dass du keine Zeit damit verbringen musst, die beste Lösung für diese Aufgaben zu finden - das ist bereits für dich erledigt. Aus der Perspektive der Säule ist es jedoch wichtig zu verstehen, wie sich diese Entscheidung für Ops and Run auf die Arbeit der anderen API-Säulen auswirkt. Wenn du eine API-Komponente in Kubernetes einsetzt, musst du ihre Einsatz-, Routing- und Skalierungskonfigurationen beschreiben. Das bedeutet, dass das Team, das die Entscheidungen in den Bereichen Design, Entwicklung und Testen trifft, auch ein gutes Verständnis von Kubernetes haben muss, damit es eine funktionierende Software erstellen kann. Theoretisch ist es eine gute Idee und entspricht dem Geist von DevOps, wenn das Entwicklungsteam für die Säulen "Operate" und "Run" entwirft und baut. Aber sei gewarnt: In der Praxis kann es schwierig (und teuer) sein, Leute mit einem so breiten Wissensfundament zu finden.

Dienstnetz

Jetzt, wo der Microservices-Stil populär geworden ist, gibt es immer mehr Softwareprodukte, die aus kleineren, strukturierten Softwaremodulen und APIs bestehen. Aber wenn du eine API in kleinere Teile zerlegst, wird es schwieriger, diese Teile funktionsfähig miteinander zu verbinden. Um diese Kosten in den Griff zu bekommen, setzen einige Teams ein Plattformkonzept ein, das als Service Mesh bezeichnet wird. Ein Service Mesh hilft, die Betriebskosten für die Kommunikation zwischen Softwarekomponenten über ein Netzwerk zu senken. Die Einführung eines Service Mesh ist oft mit hohen anfänglichen Kosten für Betrieb und Wartung verbunden, da die meisten Service Mesh-Tools nicht trivial einzurichten, zu installieren und zu warten sind. Aber ein Service Mesh kann in den Säulen Design und Entwicklung große Vorteile bieten - es gibt deinen API-Teams die Freiheit, kleinere Einsatzeinheiten so zu erstellen, dass sie sicher ausgeführt werden können.

Serverless, Low-Code und die Zukunft

Ein gemeinsamer Nenner der Laufzeitplattform-Innovationen für APIs ist, dass sie uns helfen, hoch skalierbare und hoch belastbare Software schneller und einfacher zu entwickeln. Die meisten Innovationen, die wir gesehen haben, tun dies, indem sie die Komplexitätskosten verbergen und Standardisierung einführen. Dieser Trend setzt sich mit der zunehmenden Beliebtheit von "serverlosen" Architekturen fort, die die gesamte Komplexität des Plattformbetriebs hinter einer standardisierten, ereignisgesteuerten Schnittstelle verbergen. Ebenso verbirgt der Trend zu "Low-Code"-Architekturen die Komplexität einer API-fähigen Architektur hinter einer standardisierten Entwicklungsschnittstelle.

Die Details von Serverless, Low-Code, Service Meshes und Kubernetes würden den Rahmen dieses Buches sprengen. Aus Sicht des API-Managements ist es jedoch wichtig, dass du verstehst, wie sich diese Plattforminnovationen auf die Entscheidungen und die Arbeit auswirken, die du in den einzelnen Säulen verwaltest. Wenn du zum Beispiel eine serverlose Plattform einsetzt, werden die Kosten und der Umfang deiner Entwicklungssäule erheblich reduziert, aber du brauchst Serverless-Expertise für die Säulen Design, Betrieb und Ausführung.

Zusammenfassung

In diesem Kapitel haben wir einen Rundgang durch die 10 Säulen gemacht, die die Grundlage der API-Produktarbeit bilden. In jeder Säule liegen die Entscheidungen, die sich auf das endgültige API-Produkt auswirken. Nicht alle Säulen erfordern notwendigerweise den gleichen Arbeitsaufwand, und du musst entscheiden, wie wichtig jede Säule ist, je nach Kontext und Zielen für deine API. Wenn deine API-Landschaft wächst, musst du auch darüber nachdenken, wie die Entscheidungen in jeder dieser Säulen verteilt werden sollen. Darüber werden wir in Kapitel 11 mehr sagen. Wir haben auch gesehen, dass einige Säulen in Gruppen arbeiten, was mehr Auswirkungen und Verflechtungen auf die API-Praxis als Ganzes hat. Jetzt ist es an der Zeit zu verstehen, wie man die Kosten für die Veränderung der Interaktionen im Lebenszyklus managen kann und wie man das richtige Investitionsniveau mit dem richtigen Reifegrad für deine API anwendet.

Doch bevor wir dazu kommen, müssen wir unsere 10. Säule, das Änderungsmanagement, genauer untersuchen. Wie hoch sind die Kosten für Änderungen an einer API? Darauf gehen wir im nächsten Kapitel ein.

¹ Jason Costa, "A Tale of 2 API Platforms", Medium, 25. Oktober 2016, https://oreil.ly/ZzAlj.

² Oder kontinuierliche Bereitstellung.

Get Kontinuierliches API-Management, 2. Auflage now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial