Eine API aus dem eigenen Code aufrufen

Du brauchst das Wetter von morgen in deinem Programm. Du öffnest die API-Dokumentation in einem Browser-Tab, fügst die Adresse ein und siehst eine wunderbar schöne JSON-Seite. Es funktioniert. Also kopierst du die Adresse in deinen Code, führst ihn aus — und das Programm stürzt mit einer Wand aus Text ab. An der API hat sich zwischen diesen beiden Momenten nichts geändert. Geändert hat sich, wer gefragt hat.

GET /v1/weather?city=Berlin HTTP/1.1
Host: api.example.org
Accept: application/json


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

{"city": "Berlin", "tempC": 14}

req:
  GET /v1/weather?city=Berlin

res:
  status = 200
  body.tempC = 14

if (status != 200) -> error
body.tempC

Dein Browser ist ein Programm, das still eine Menge zusätzliche Arbeit für dich erledigt. Er speichert Cookies, damit du angemeldet bleibst. Er folgt Weiterleitungen und zeigt dir die letzte Seite, ohne die drei Sprünge dazwischen zu erwähnen. Er wiederholt die Anfrage, wenn die Verbindung abreißt. Er führt das JavaScript aus, ohne das eine moderne Seite gar nichts anzeigt. Und wenn ein 404 kommt, malt er fröhlich eine hübsche Fehlerseite, sodass die Anfrage erfolgreich aussieht. Dein Programm macht nichts davon, solange du es nicht selbst schreibst. Ein Statuscode 404 ist für deinen Code keine Fehlerseite, sondern eine Zahl, die du prüfen musst — und wenn du sie nicht prüfst, wirst du fröhlich versuchen, Wetterdaten aus einer Fehlermeldung zu lesen.

Es gibt noch eine Familie, die dir im echten Code ständig begegnet: 3xx. Eine Weiterleitung ist der Server, der sagt: „Nicht hier, schau dort drüben.“ Ein Browser folgt ihr für dich, und du merkst es nie. Dein HTTP-Client tut es vielleicht oder vielleicht nicht, je nachdem, wie er eingestellt ist — und davon hängt ab, welche Daten du am Ende hast.

Ein Timeout sagt: Ich warte so und so lange auf eine Antwort, dann höre ich auf und behandle es als Fehlschlag. Ohne ihn wartet dein Programm ewig auf einen Server, der nie antworten wird: Der Knopf dreht sich, die Anfrage endet nie, und der Nutzer hat keine Ahnung, was los ist. Zwei Sekunden sind eine normale Wahl für eine Anfrage, auf die ein Mensch wartet. Die wichtige Folge: Ein Timeout ist kein Beweis, dass die Anfrage nicht passiert ist. Die andere Seite hat sie vielleicht bekommen und die Arbeit erledigt, und nur die Antwort ist auf dem Rückweg verloren gegangen.

Ein vernünftiger Zahlungsablauf sieht also so aus: Gib jedem Versuch einen eindeutigen Schlüssel, schick ihn mit der Anfrage und setz der Anfrage ein Timeout. Läuft die Anfrage in den Timeout, schick sie mit demselben Schlüssel noch einmal. Ist das Geld schon unterwegs, erkennt die andere Seite den Schlüssel und sagt es dir, statt erneut abzubuchen. Und du wiederholst niemals endlos: ein paar Versuche mit wachsender Pause dazwischen, dann aufgeben und es dem Nutzer ehrlich sagen.