APIs, JSON und wie getrennte Systeme zusammenarbeiten

Was eine API ist

Eine API (Programmierschnittstelle) ist der definierte Weg, auf dem eine Software eine andere bittet, etwas zu tun. Sie legt fest, was angefragt werden kann, was mitgeliefert werden muss, was zurückkommt und was schiefgehen kann. Das entscheidende Wort ist definiert: Eine API ist ein Vertrag. Der Anbieter verspricht, sie funktionsfähig zu halten; der Nutzer verspricht, nur das zu verwenden, was sie beschreibt.

Ein Restaurant ist die übliche Analogie. Die Speisekarte führt auf, was Sie bestellen können und was jedes Gericht enthält; der Kellner bringt Ihre Bestellung in die Küche und das Ergebnis zurück. Sie gehen nicht in die Küche, und Sie müssen nicht wissen, ob der Koch mit Gas oder Induktion kocht. Die Küche kann Ausstattung, Personal und Lieferanten nach Belieben wechseln, solange die Gerichte auf der Karte weiterhin wie beschrieben ankommen. Die Speisekarte ist die API, die Küche ist die Implementierung, und die Trennung zwischen beiden erlaubt es beiden Seiten, sich unabhängig zu ändern.

Das ist derselbe Gedanke wie bei den Schnittstellen in Code organisieren, angewandt auf jeder Ebene. Es ist auch der Grund, warum Architekten APIs so wichtig nehmen: An einer API trifft die Arbeit eines Teams auf die eines anderen, und sobald andere von ihr abhängen, ist sie teuer zu ändern.

In-Process-APIs und Web-APIs

Manche APIs werden innerhalb eines laufenden Programms aufgerufen. Wenn Python-Code json.loads(text) aufruft, nutzt er die API des Moduls json der Standardbibliothek: ein Funktionsaufruf, der Nanosekunden dauert und nur scheitert, wenn die Eingabe fehlerhaft ist. Die öffentlichen Funktionen und Klassen einer Bibliothek sind ihre In-Process-API.

Eine Web-API wird über ein Netzwerk aufgerufen, meist mit HTTP (siehe Wie Computer kommunizieren). Aufrufer und Anbieter können auf verschiedenen Maschinen laufen, in verschiedenen Sprachen geschrieben sein und verschiedenen Organisationen gehören. Eine Mobile-Banking-App spricht mit der Web-API der Bank; die Server der Bank sprechen mit der API eines Kartennetzwerks; ein Shop spricht mit der API eines Zahlungsanbieters.

Der Unterschied ist nicht kosmetisch. Ein Netzwerkaufruf ist tausend- bis millionenfach langsamer als ein Funktionsaufruf, und er kann auf eine Weise scheitern, wie es ein Funktionsaufruf nicht kann: Das Netzwerk verliert die Anfrage, der Server ist überlastet, die Antwort kommt an, nachdem der Aufrufer aufgegeben hat, oder die Anfrage war erfolgreich, aber die Antwort ging verloren, sodass der Aufrufer nicht erkennen kann, ob die Zahlung durchging. Ein Großteil des Entwurfs verteilter Systeme, behandelt in Kapitel 6, dreht sich darum, mit diesen Ausfällen zu leben.

REST: Ressourcen, URLs und Verben

Die meisten Web-APIs folgen heute dem Stil namens REST (Representational State Transfer), den Roy Fielding in seiner Dissertation von 2000 beschrieb. Fielding definierte REST als eine Reihe von Randbedingungen für große vernetzte Systeme wie das Web; im Alltag meint „eine REST-API“ etwas Einfacheres: eine HTTP-API, die um Ressourcen herum organisiert ist.

Eine Ressource ist etwas, das die API bereitstellt: ein Kunde, eine Bestellung, eine Prognose. Jede hat eine URL, etwa /orders/1042. Auch eine Sammlung davon hat eine URL, etwa /orders. Der Client wirkt mit den Standard-HTTP-Methoden auf Ressourcen ein, liest den Statuscode des Ergebnisses und tauscht Daten im Body aus, meist als JSON. Dieselben wenigen Verben funktionieren daher für jede Ressource, was gut entworfene REST-APIs vorhersehbar macht.

Statuscodes tragen eine Bedeutung, auf die ein Client-Programm reagieren kann. Ein 4xx-Code besagt, dass der Client etwas falsch gemacht hat: 400 bei einer fehlerhaften Anfrage, 401, wenn Zugangsdaten fehlen oder ungültig sind, 403, wenn der Aufrufer bekannt, aber nicht berechtigt ist, 404, wenn die Ressource nicht existiert, 429, wenn er zu viele Anfragen gesendet hat. Ein 5xx-Code besagt, dass der Server versagt hat: 500 bei einem unerwarteten Fehler, 503, wenn er vorübergehend nicht verfügbar ist. Die Unterscheidung ist wichtig, weil eine unveränderte Wiederholung einer 4xx-Anfrage erneut scheitert, während eine Wiederholung nach einem 503 etwas später gelingen kann.

Daten werden als JSON (JavaScript Object Notation) übertragen, einem Textformat, das als RFC 8259 standardisiert ist. Es hat nur wenige Bausteine: Objekte (Name-Wert-Paare in geschweiften Klammern), Arrays (Listen in eckigen Klammern), Zeichenketten in doppelten Anführungszeichen, Zahlen, true, false und null. Trotz des Namens kann jede gängige Sprache es lesen und schreiben, weshalb es zur gemeinsamen Sprache der Web-APIs wurde. Es gibt andere Stile für andere Bedürfnisse: Bei GraphQL gibt der Client genau an, welche Felder er haben will, und gRPC nutzt ein kompaktes Binärformat für schnelle Aufrufe zwischen Services; Kapitel 6 vergleicht sie.

GET /v1/forecast?city=Kigali&days=2 HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_test_4f9a...
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "city": "Kigali",
  "units": "metric",
  "days": [
    {"date": "2026-10-23", "min_c": 16, "max_c": 27, "rain_chance": 0.6},
    {"date": "2026-10-24", "min_c": 16, "max_c": 26, "rain_chance": 0.4}
  ]
}

import os
import requests

API_KEY = os.environ["WEATHER_API_KEY"]   # never hard-code secrets

resp = requests.get(
    "https://api.example.com/v1/forecast",
    params={"city": "Kigali", "days": 2},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=3,                 # give up after 3 seconds
)
resp.raise_for_status()        # raises an error for 4xx and 5xx
tomorrow = resp.json()["days"][0]
print(tomorrow["max_c"], "degrees, rain chance", tomorrow["rain_chance"])

Wer ruft an? API-Schlüssel und Tokens

Die meisten APIs müssen wissen, wer aufruft, um abzurechnen, zu begrenzen und zu entscheiden, was der Aufrufer sehen darf. Zwei Begriffe sollte man von Anfang an trennen. Authentifizierung beantwortet „Wer sind Sie?“; Autorisierung beantwortet „Was dürfen Sie tun?“

Ein API-Schlüssel ist eine lange geheime Zeichenkette, die die aufrufende Anwendung identifiziert und mit jeder Anfrage gesendet wird, typischerweise in einem Header. Er ist einfach und identifiziert ein Programm, keine Person. Ein Access Token ist ein kurzlebiger Berechtigungsnachweis, der nach einer Anmeldung ausgestellt wird, oft im Namen eines bestimmten Nutzers und mit bestimmten Berechtigungen („den Kalender dieses Nutzers lesen, aber nicht seine E-Mails“); er wird meist als Authorization: Bearer <token> gesendet. Tokens laufen ab, sodass ein gestohlenes nur begrenzte Zeit nützt. Die zugrunde liegenden Standardprotokolle, OAuth 2.0 und OpenID Connect, werden in Identität und Zugriff behandelt.

Was auch immer verwendet wird, die Regeln sind dieselben: Zugangsdaten nur über HTTPS senden, sie aus dem Quellcode heraushalten und aus mobilen Apps, aus denen jeder sie extrahieren kann, sie in einem Secrets Manager oder in Umgebungseinstellungen speichern und sie schnell widerrufen und ersetzen können.

Webhooks: Die API ruft Sie zurück

Manchmal muss der Client wissen, wann auf der Seite des Anbieters etwas geschieht: Eine Zahlung gelingt, ein Paket wird zugestellt, ein Dokument wird unterschrieben. Der Client könnte pollen, also alle paar Sekunden fragen „Ist es schon passiert?“, was Anfragen verschwendet und es trotzdem spät bemerkt. Ein Webhook kehrt die Richtung um: Der Client registriert eine eigene URL, und der Anbieter sendet ein HTTP-POST an diese URL, wenn das Ereignis eintritt. Den Begriff prägte Jeff Lindsay 2007.

Webhooks bringen Pflichten mit sich. Der empfangende Endpoint steht im öffentlichen Internet, daher muss er prüfen, dass jeder Aufruf wirklich vom Anbieter stammt, meist durch Verifizieren einer kryptografischen Signatur in einem Header. Anbieter wiederholen den Versand, wenn der Empfänger nicht antwortet, sodass dasselbe Ereignis zweimal ankommen kann und der Empfänger Duplikate erkennen muss (die Verarbeitung eines Duplikats darf die Bestellung nicht zweimal versenden). Und Ereignisse können in falscher Reihenfolge ankommen.

Auf eine Antwort warten oder nicht: synchron und asynchron

Alles bisher war synchron: Der Aufrufer sendet eine Anfrage und wartet auf die Antwort, bevor er weitermacht, wie bei einem Telefonat. Das ist leicht nachzuvollziehen und die richtige Wahl, wenn der Aufrufer die Antwort wirklich sofort braucht, etwa „Wurde diese Kartenzahlung genehmigt?“. Die Schwäche: Der Aufrufer ist nur so verfügbar und so schnell wie alles, worauf er wartet.

Die Alternative ist asynchrones Messaging, eher wie ein Brief, den man in einen Briefkasten wirft. Der Sender legt eine Nachricht in eine Message Queue und macht weiter. Der Empfänger holt Nachrichten aus der Queue, wenn er bereit ist. Ist der Empfänger langsam oder eine Stunde lang ausgefallen, warten die Nachrichten, statt zu scheitern. Wenn der Shop eine Bestellung bestätigt, muss das Senden der Bestätigungs-E-Mail den Bildschirm des Kunden nicht aufhalten; eine Nachricht OrderPlaced kann in eine Queue gehen, die der E-Mail-Service einen Moment später abarbeitet.

Asynchronität ist nicht kostenlos. Der Sender erfährt nicht sofort, ob die Arbeit gelungen ist, das System wird schwerer nachzuverfolgen und zu testen, und Nachrichten können mehr als einmal zugestellt werden. Die Entscheidung, welche Interaktionen synchron und welche asynchron sein sollen, ist eine der zentralen Entscheidungen in verteilten Systemen und wird ausführlich in Kommunikation und APIs und Queues und Backpressure behandelt.

Mit den APIs anderer leben: SDKs, Versionen und Limits

Viele Anbieter veröffentlichen ein SDK (Software Development Kit): eine Bibliothek für jede verbreitete Sprache, die die HTTP-Aufrufe in gewöhnliche Funktionen verpackt, sodass ein Entwicklungsteam client.refunds.create(payment_id) schreibt, statt Anfragen von Hand zu bauen. SDKs sparen Zeit und kümmern sich um Details wie Wiederholungen und Signaturen, sind aber eine weitere Abhängigkeit, die aktuell gehalten werden muss.

Sobald eine API Nutzer hat, wird jede Änderung heikel. Ein neues optionales Feld in einer Antwort hinzuzufügen, ist meist unbedenklich. Ein Feld umzubenennen, zu entfernen, seinen Typ oder seine Bedeutung zu ändern oder eine optionale Eingabe zur Pflicht zu machen, ist ein Breaking Change: Jeder Client, der sich auf das alte Verhalten verlassen hat, bricht, oft in Produktion und oft bei einem Anbieter, der diese Clients weder sehen noch aktualisieren kann (denken Sie an mobile Apps, die Nutzer nie aktualisieren). Anbieter versionieren ihre APIs daher, zum Beispiel mit /v1/ und /v2/ in der URL oder mit einem Versions-Header, lassen die alte Version für einen veröffentlichten Zeitraum weiterlaufen und kündigen Deprecations (Hinweise, dass eine Funktion zurückgezogen wird) lange im Voraus an. Hyrum Wrights Beobachtung, bekannt als Hyrums Gesetz, fügt eine Warnung hinzu: Bei genügend Nutzern hängt jemand von jedem beobachtbaren Verhalten einer API ab, auch von solchem, das die Dokumentation nie versprochen hat.

Anbieter schützen sich außerdem mit einem Rate Limit: einer Obergrenze wie 100 Anfragen pro Minute und Schlüssel. Anfragen über dem Limit werden mit Status 429 Too Many Requests abgelehnt, oft mit einem Retry-After-Header, der angibt, wann man es erneut versuchen kann. Clients sollten das respektieren, ihre Anfragen verteilen, Antworten zwischenspeichern, die sich selten ändern, und sich zurückhalten, wenn sie dazu aufgefordert werden.

Drittanbieter-APIs nutzen: selbst bauen oder einkaufen

Moderne Anwendungen werden ebenso zusammengesetzt wie geschrieben. Eine Essensliefer-App nutzt vielleicht die API eines Zahlungsanbieters für Kartenzahlungen, eine Karten-API für Adressen und Routen, eine E-Mail- oder SMS-API für Belege und einen Push-Benachrichtigungsdienst für „Ihr Fahrer ist in der Nähe“. Jede davon spart Monate an Spezialistenarbeit und bringt Fachwissen mit (Kartensicherheit, globale Kartendaten, E-Mail-Zustellbarkeit), mit dem nur wenige Teams mithalten könnten.

Jede bringt aber auch eine Abhängigkeit mit, die das Team nicht kontrolliert: Die Ausfälle des Anbieters werden zu Ihren Ausfällen, seine Preisänderungen zu Ihren Kosten, sein Umgang mit Daten wird Teil Ihrer Compliance, und ein Wechsel kann bedeuten, Code neu zu schreiben. Fachleute steuern das bewusst. Sie isolieren jeden Anbieter hinter einer kleinen eigenen Schnittstelle, sodass nur ein Teil des Codes die API des Anbieters kennt; sie setzen Timeouts und legen fest, was geschieht, wenn der Anbieter ausgefallen ist; sie beobachten die Statusseite und das Änderungsprotokoll des Anbieters; und sie halten fest, was ein Wechsel kosten würde.

Warum das für die Architektur wichtig ist

Architektur dreht sich weitgehend um die Teile eines Systems und die Verträge zwischen ihnen, und APIs sind diese Verträge in konkreter Form. Eine API, die sich leicht richtig nutzen und schwer kaputt machen lässt, lässt Teams parallel arbeiten und ihr Innenleben frei ändern; eine undichte oder instabile koppelt alle an alle. Die Wahl zwischen synchronen Aufrufen und asynchronen Nachrichten bestimmt, wie sich Ausfälle ausbreiten. Kapitel 3 erklärt die Prinzipien hinter guten Schnittstellen (Information Hiding, Abstraktion und Schnittstellen), und Kapitel 6 zeigt, wie Entscheidungen über APIs und Messaging verteilte Systeme gelingen oder scheitern lassen.