Was ist eine API?

Einfach erklärt

Denken Sie an die Essensausgabe einer Kantine. Niemand geht in die Küche. Man bestellt am Schalter aus einer festen Auswahl und die Küche entscheidet, was sie herausgibt. Eine API ist ein solcher Schalter für Programme. Ihr Onlineshop gibt darüber Bestellungen an die Buchhaltung weiter, die Formular-App schickt Berichte an die Dokumentenablage. Niemand muss exportieren, abtippen oder Dateien hin- und herschicken.

API steht für Application Programming Interface, auf Deutsch Programmierschnittstelle. Im Alltag heißt sie meist einfach Schnittstelle.

Was ein API-Schlüssel ist

Damit nicht jeder am Schalter bestellen kann, braucht ein Programm einen Schlüssel, eine lange Zeichenfolge. Wer ihn hat, kann in Ihrem Namen Daten lesen und je nach Rechten auch ändern oder löschen. Behandeln Sie API-Schlüssel deshalb wie Passwörter: nicht per Mail verschicken, nicht in Listen notieren, sondern im Passwortmanager ablegen. Jede Anbindung bekommt einen eigenen Schlüssel mit so wenig Rechten wie möglich. Endet die Zusammenarbeit mit einem Dienstleister, werden seine Schlüssel gelöscht.

Worauf Sie bei der Auswahl von Software achten

Fragen Sie vor dem Kauf: Gibt es eine dokumentierte API? Ist sie in Ihrem Tarif enthalten? Lassen sich darüber alle Ihre Daten wieder herausholen? Davon hängt später ab, ob Sie Programme verbinden und den Anbieter wechseln können.

Was eine API nicht leistet

Dass eine API vorhanden ist, heißt noch nicht, dass zwei Programme verbunden sind. Jemand muss die Verbindung bauen und pflegen, etwa Ihr IT-Dienstleister oder eine Workflow-Automatisierung. Ändert ein Anbieter seine API, kann eine Anbindung ausfallen.

REST über HTTP

Verbreitet sind Web-APIs im Architekturstil REST, den Roy Fielding 2000 in Kapitel 5 seiner Dissertation beschrieben hat. Ressourcen haben URLs, die HTTP-Methode bestimmt die Operation: GET liest, POST legt an, PUT ersetzt, DELETE löscht (RFC 9110), PATCH ändert teilweise (RFC 5789). Die Daten sind meist JSON nach RFC 8259. Maschinenlesbar beschrieben wird eine API häufig nach der OpenAPI Specification.

curl -i "https://api.example.de/v1/auftraege?status=offen&page=1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

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

{"count": 57, "next": "https://api.example.de/v1/auftraege?status=offen&page=2", "results": […]}

Für Wiederholungen wichtig: PUT und DELETE sind nach RFC 9110 Abschnitt 9.2.2 idempotent, POST nicht. Ein blind wiederholter POST kann einen Datensatz doppelt anlegen.

Authentifizierung

Einfache APIs arbeiten mit einem festen API-Schlüssel, oft als Bearer Token im Header Authorization (RFC 6750 Abschnitt 2.1). In die URL gehört er nicht, weil URLs in Protokollen landen. RFC 6750 Abschnitt 2.3 rät davon ab. Für Zugriffe im Namen eines Benutzers mit begrenzter Laufzeit gibt es OAuth 2.0 (RFC 6749). Der Status 401 bedeutet fehlende oder ungültige Anmeldung, 403 eine erkannte Anmeldung ohne Berechtigung (RFC 9110 Abschnitt 15.5.2 und 15.5.4).

Typische Fehler

• Schlüssel im Quellcode. Einmal eingecheckt, steht er in der Historie des Repositorys, auch nach dem Löschen.
• Ein Schlüssel für alles. Ein Administrator-Token für eine Anbindung, die nur lesen muss.
• Nur die erste Seite gelesen. Wer next oder page nicht auswertet, verliert Datensätze, ohne dass ein Fehler erscheint.
• 429 ignoriert. 429 Too Many Requests (RFC 6585 Abschnitt 4) meldet ein Anfragelimit, oft mit Retry-After (RFC 9110 Abschnitt 10.2.3). Wer sofort wiederholt, statt zu warten, läuft erneut ins Limit.
• Schlüssel ohne Ablauf. Schlüssel früherer Dienstleister bleiben gültig, bis jemand sie widerruft.

Prüfen

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $API_TOKEN" https://api.example.de/v1/auftraege

Erwartet ist 200 mit gültigem Schlüssel, 401 ohne Schlüssel und 403 mit einem Schlüssel ohne Recht auf die Ressource. Liefert die API ohne Schlüssel Daten, fehlt die Anmeldung ganz.