API-Plattform aufbauen: Vertrag, Sicherheit und Partner

Das erste Versprechen der Plattform festlegen

Wer eine API-Plattform aufbauen möchte, braucht ein erstes Versprechen, das ein Produktteam in einem Satz erklären kann. Zum Beispiel: „Ein Händler kann die Produktverfügbarkeit mit seinem Warenwirtschaftssystem synchronisieren.“ Dieses Versprechen benennt einen konkreten Nutzer, ein anzubindendes System und ein Ergebnis, das vor dem Launch getestet werden kann.

Wählen Sie den ersten Integrationspartner sorgfältig aus. Das kann ein internes Entwicklungsteam, ein benannter Designpartner oder ein Softwareanbieter sein, der Ihre Kunden bereits betreut. Jede Gruppe bringt andere Erwartungen mit: Ein internes Team kennt möglicherweise Ihr Datenmodell, während ein externer Partner klare Einrichtungsanweisungen und vorhersehbare Antworten benötigt.

Listen Sie die wichtigsten Anwendungsfälle auf und markieren Sie anschließend, was die erste Version nicht unterstützen wird. Eine Commerce-API könnte Partnern ermöglichen, Produktdetails abzurufen und Bestellungen aufzugeben, während Rückerstattungen oder der Massenimport von Katalogen einer späteren Version vorbehalten bleiben. Eine klare Abgrenzung verhindert, dass aus einem Pilotprojekt stillschweigend die Zusage wird, jede gewünschte Funktion zu entwickeln.

Eine API-first-Plattform zeichnet sich nicht einfach durch vorhandene Endpunkte aus. Die erste Version sollte einem bestimmten Integrationspartner ermöglichen, eine konkrete Aufgabe zu erledigen, ohne auf verborgenes Wissen angewiesen zu sein. Wenn Ihr Produkt Inhalte für den Onlineshop und Commerce-Prozesse umfasst, gleichen Sie die Integrationsgrenzen mit Ihren übergeordneten Entscheidungen zur CMS-Plattform für digitalen Handel ab, bevor Sie den Umfang endgültig festlegen.

Den API-Vertrag verbindlich festlegen

So lassen sich API-Vertrag und API-Spezifikation erstellen, bevor Sie den ersten Endpunkt veröffentlichen. Benennen Sie Ressourcen einheitlich, beschreiben Sie Pflichtfelder und optionale Felder und fügen Sie für jede Operation eine repräsentative Anfrage und Antwort hinzu. Wenn eine Bestellung Einzelpositionen enthält, dokumentieren Sie, ob eine leere Liste zulässig ist und was geschieht, wenn eine Produkt-ID unbekannt ist.

Beschreiben Sie Fehler präzise. Nutzer der API müssen ungültige Eingaben von abgelaufenen Zugangsdaten oder vorübergehenden Dienstproblemen unterscheiden können. Jeder Fehler sollte einen stabilen Code und eine hilfreiche Erklärung enthalten. Geben Sie weder Stacktraces noch interne Hostnamen in einer Antwort preis – solche Details können aus einem gewöhnlichen Integrationsfehler ein Sicherheitsproblem machen.

Für Operationen, die Datensätze erstellen oder ändern, brauchen Sie eine ausdrückliche Idempotenzregel. Wenn ein Partner eine zahlungsbezogene Anfrage nach einer Netzwerk-Zeitüberschreitung erneut sendet, müssen Sie festlegen, ob derselbe Idempotenzschlüssel das ursprüngliche Ergebnis zurückgibt oder eine zweite Operation auslöst. Dokumentieren Sie, wie lange Schlüssel gültig sind und was passiert, wenn derselbe Schlüssel mit anderen Daten gesendet wird.

Kompatibilitätsregeln sind ebenso wichtig wie Feldnamen. Legen Sie fest, ob ein zusätzliches optionales Antwortfeld für API-Nutzer unbedenklich ist, wie eine Änderung an einem Pflichtfeld angekündigt wird und ob Clients unbekannte Felder ignorieren sollen. Halten Sie ein Beispielschema neben der schriftlichen Regel bereit – ein Satz allein macht möglicherweise nicht deutlich, dass ein Feld tatsächlich erforderlich ist.

Klärungsbedarf sollte frühzeitig in einer Vertragsprüfung ausgeräumt werden. Bitten Sie Produktmanagement, Entwicklung und Support, dieselbe Beispielanfrage zu prüfen, und halten Sie die Entscheidungen in der API-Spezifikation fest. Eine ungeklärte Frage zum Datumsformat kann sonst in drei Partnerintegrationen zu unterschiedlichen Auslegungen führen.

Zugriffs- und Mandantenkontrollen einrichten

Legen Sie fest, wie ein Integrationspartner seine Zugangsdaten erhält, bevor Sie ihn in die Produktionsumgebung einladen, und wie Sie API-Zugriff und Berechtigungen sicher verwalten. Ein namentlich benannter Kontoinhaber, eine verifizierte Rückrufadresse und ein dokumentierter Freigabeschritt sorgen für eine nachvollziehbare Vergabe. Versenden Sie langlebige Geheimnisse nicht einfach in einem gewöhnlichen E-Mail-Verlauf. Nutzen Sie einen kontrollierten Übermittlungsweg und erklären Sie dem Empfänger, wo die Zugangsdaten sicher aufzubewahren sind.

Planen Sie Rotation und Sperrung als reguläre Abläufe ein, nicht nur für den Notfall. Ein Partner sollte wissen, wie er Zugangsdaten austauschen kann, ohne einen geplanten Abgleich zu unterbrechen. Ihr Team sollte außerdem einen kompromittierten Schlüssel sperren können, ohne andere Kunden zu beeinträchtigen. Testen Sie beide Abläufe mit einem Nicht-Produktionskonto.

Berechtigungsbereiche sollten zum jeweiligen Zweck passen. Eine Reporting-Integration benötigt möglicherweise Lesezugriff auf Produkte und Bestellungen, aber keine Berechtigung, Fulfillment-Einstellungen zu ändern. Erklären Sie jeden Berechtigungsbereich in klarer Sprache und prüfen Sie anschließend, ob die API Vorgänge außerhalb der gewährten Berechtigungen ablehnt, statt sie stillschweigend zu akzeptieren.

Mandantentrennung erfordert mehr, als lediglich eine Kunden-ID in eine URL einzufügen. Vergewissern Sie sich, dass Zugangsdaten eines Mandanten nicht zum Lesen oder Ändern der Datensätze eines anderen Mandanten verwendet werden können – auch nicht über Filter, Exporte oder Fehlerinformationen. Mit einem separaten Testkonto für jeden Mandanten lässt sich diese Prüfung einfacher wiederholen.

Legen Sie Nutzungslimits fest und erklären Sie ihre Auswirkungen. Definieren Sie, was API-Nutzer sehen, wenn sie ein Limit erreichen, ob eine Anfrage erneut gesendet werden kann und wie ein Partner eine Überprüfung beantragt. Verknüpfen Sie den Umgang mit Zugangsdaten mit Ihren allgemeinen Maßnahmen zur Website-Sicherheit, insbesondere mit der sicheren Speicherung von Geheimnissen, Zugriffsprüfungen und der Reaktion auf Sicherheitsvorfälle.

Einen Testpfad für API-Nutzer vorbereiten

Eine Sandbox bietet Integrationspartnern die Möglichkeit, die API kennenzulernen, ohne echte Kundendaten zu verändern. Ihr Verhalten sollte der Produktionsumgebung möglichst nahekommen; Abweichungen müssen jedoch klar gekennzeichnet sein. Wenn Sandbox-Ereignisse auf Abruf statt durch echte Transaktionen erzeugt werden, weisen Sie im Einrichtungsleitfaden darauf hin.

Stellen Sie Testdaten für gewöhnliche und schwierige Fälle bereit. Dazu gehören ein Produkt ohne verfügbaren Lagerbestand, eine Bestellung mit mehreren Positionen und eine Anfrage, die an der Validierung scheitert. Anhand dieser Beispiele können API-Nutzer sowohl den Erfolgsfall als auch das Verhalten prüfen, das ihr Code bei Fehlern bewältigen muss.

Funktionierende Beispiele sollten sich mit möglichst wenigen Änderungen ausführen lassen. Zeigen Sie den Authentifizierungsschritt, die Anfrage und eine repräsentative Antwort in der Sprache, die Ihr erster Integrationspartner verwendet. Benennen Sie Werte, die eingesetzt werden müssen, eindeutig. Ein Platzhalter wie YOUR_API_KEY ist hilfreicher als eine nicht erklärte Zeichenfolge, die echt aussieht.

Der Weg, um Integrationsprobleme zu melden, sollte leicht zu finden sein. Nennen Sie den Supportkanal, listen Sie auf, welche Angaben enthalten sein sollen – Zeitstempel der Anfrage, Endpunkt, Korrelations-ID und bereinigte Antwort – und weisen Sie darauf hin, welche Informationen nicht gesendet werden dürfen, etwa ein vollständiger geheimer Schlüssel. Eine kurze Vorlage kann mehrere Rückfragen ersparen.

Bitten Sie vor der Veröffentlichung jemanden außerhalb des API-Teams, den Leitfaden in einer frischen Umgebung Schritt für Schritt durchzugehen. Stellen Sie dieser Person ausschließlich die veröffentlichte Dokumentation und Sandbox-Zugangsdaten zur Verfügung. Wenn sie für einen fehlenden Schritt die Erklärung eines Entwicklers benötigt, halten Sie die Lücke fest und schließen Sie sie, bevor Sie den nächsten API-Nutzer an Bord holen.

Releases und Änderungen organisieren

Dokumentieren Sie die Versionsregeln, bevor der erste Partner von der API abhängig ist. Legen Sie fest, wie inkompatible Änderungen gekennzeichnet werden, wie lange eine ältere Version verfügbar bleibt und wer Änderungen am Verhalten von Anfragen oder Antworten freigeben darf. Ohne eine verantwortliche Person kann schon eine kleine Änderung am Schema zu einem Ausfall bei einem Partner führen.

Weisen Sie für jede öffentliche Änderung eine Person oder ein Team als verantwortlich aus. Diese Zuständigen sollten Vertrag, Beispiele, automatisierte Tests und Release Notes gemeinsam prüfen. Eine Änderung ist nicht allein deshalb bereit, weil der Endpunkt in der Entwicklungsumgebung funktioniert. API-Nutzer benötigen genügend Informationen, um ihren eigenen Code anzupassen.

Änderungsprotokolle sollten die Auswirkungen beschreiben und nicht bloß Commit-Namen auflisten. „Die Bestellungsantwort enthält jetzt einen Fulfillment-Status“ erklärt API-Nutzern, was sich geändert hat; „Bestellungsmodell aktualisieren“ tut das nicht. Geben Sie den betroffenen Endpunkt, den erforderlichen Handlungsbedarf und das geltende Datum oder die jeweilige Release-Bedingung an. Stellen Sie unsichere Termine nicht als feste Zusagen dar.

Eine Migrationsanleitung sollte das alte und das neue Verhalten direkt gegenüberstellen. Wird ein Feld umbenannt, erklären Sie, ob beide Namen während einer Übergangsphase funktionieren und wann der alte Name nicht mehr unterstützt wird. Geben Sie API-Nutzern die Möglichkeit, den Ersatz in der Sandbox zu testen, bevor sie ihren Produktionscode ändern.

Den Produktionsdienst überwachen

Erfassen Sie Fehler und Latenz für jeden Endpunkt einzeln, nicht nur als Gesamtwert für den Dienst. Ein guter Durchschnitt kann einen langsamen Endpunkt zur Auftragserstellung oder einen sprunghaften Anstieg fehlgeschlagener Authentifizierungen verbergen. Versehen Sie jede Anfrage mit einer Korrelations-ID, damit der Support die Meldung eines API-Nutzers dem passenden Diensteintrag zuordnen kann.

Legen Sie Alarmgrenzwerte fest und bestimmen Sie, wer dafür verantwortlich ist und welche Maßnahmen folgen sollen. Ein Alarm, den niemand überwacht, ist nur eine weitere Farbe auf einem Dashboard. Legen Sie für jeden Alarm fest, wer ihn erhält, was zuerst überprüft werden soll und wann der Vorfall an die für den Dienst verantwortliche Person weiterzugeben ist.

Legen Sie fest, welche Betriebsdaten gespeichert werden und aus welchem Grund. Anfrageprotokolle können bei der Fehlersuche helfen, aber auch personenbezogene oder geschäftlich sensible Informationen enthalten, wenn Teams vollständige Nutzdaten protokollieren. Definieren Sie, welche Felder gespeichert werden, wer darauf zugreifen darf und wie lange sie verfügbar bleiben. Prüfen Sie vor dem Launch, ob die Aufbewahrungseinstellungen zu Ihrer tatsächlichen Infrastruktur passen.

Trennen Sie die Betriebsüberwachung von der Produktanalyse. Ein Latenzdiagramm zeigt möglicherweise, dass eine Anfrage zu lange gedauert hat, während ein Integrations-Dashboard darauf hinweisen kann, dass ein API-Nutzer keine Aktualisierungen mehr sendet. Für diese Signale sind unterschiedliche Zuständige und Folgemaßnahmen erforderlich. Dokumentieren Sie beide Abläufe im Runbook.

Fehlerfälle und Support proben

Führen Sie mit den Personen, die einen echten Vorfall bearbeiten würden, eine Probe für Fehlerfälle durch. Simulieren Sie abgelaufene Zugangsdaten, eine langsame Abhängigkeit und eine Anfrage, bei der es nach dem Absenden durch den API-Nutzer zu einer Zeitüberschreitung kommt. Prüfen Sie in jedem Fall, wer die erste Meldung entgegennimmt und wer eine Wiederherstellungsmaßnahme freigeben kann.

Beschreiben Sie den Eskalationsweg ganz konkret. Legen Sie fest, über welchen Supportkanal eine Partnermeldung eingeht, welches Team die API untersucht und wer eine Kundeninformation freigibt. Kann die zuerst reagierende Person anhand des Runbooks nicht feststellen, wer für den Dienst verantwortlich ist, ist die Übergabe noch nicht ausreichend vorbereitet.

Bereiten Sie Kundeninformationen vor, in denen bestätigte Fakten klar von laufenden Untersuchungen unterschieden werden. Eine hilfreiche erste Nachricht kann den betroffenen Vorgang, den bestätigten Beginn des Problems und den Zeitpunkt des nächsten Updates nennen. Versprechen Sie keinen Zeitpunkt für die Wiederherstellung, solange die Einsatzleitung keine ausreichenden Belege dafür hat.

Testen Sie Wiederherstellungsverfahren in einer kontrollierten Umgebung. Wenn nach einem Ausfall eine Warteschlange erneut verarbeitet werden muss, prüfen Sie, wie doppelte Ereignisse verhindert werden und wie das Team kontrolliert, ob alle Datensätze wieder auf dem aktuellen Stand sind. Halten Sie fest, wer die erneute Verarbeitung freigibt und welche Nachweise vorliegen müssen, bevor der normale Betrieb wieder aufgenommen wird.

Halten Sie zum Abschluss der Probe jede Lücke mit einer verantwortlichen Person und einer konkreten Maßnahme fest, zum Beispiel mit dem Ergänzen eines fehlenden Alarms oder der Korrektur des Sandbox-Leitfadens. Bewahren Sie die Ergebnisse zusammen mit dem Release-Datensatz auf, damit bei der nächsten API-Änderung die Erkenntnisse aus dem letzten Test berücksichtigt werden.