Eine API ist eine festgelegte Schnittstelle, über die ein Programm die Funktionen eines anderen benutzt. Die Abkürzung steht für Application Programming Interface.
- API
Eine festgelegte Schnittstelle, über die ein Programm die Funktionen eines anderen benutzt.
Beispiel: „Über die API des Zahlungsdienstleisters fragt der Shop ab, ob die Zahlung eingegangen ist.“Auch: Programmierschnittstelle, Schnittstelle. Wer die API anbietet, heißt Anbieter; wer sie benutzt, Konsument.
Abgrenzung zur Benutzeroberfläche: Die ist für Menschen gemacht, die API für Programme. Dieselbe Anwendung hat oft beides, auf denselben Daten.
Was eine API vereinbart
Vier Dinge, und alle vier sind ein Versprechen. Welche Aufrufe es gibt, welche Angaben sie erwarten, was sie zurückgeben und wie Fehler aussehen. Der Wert einer API liegt darin, dass diese Vereinbarung stabil bleibt: Wer sie benutzt, baut darauf, und jede unangekündigte Änderung bricht fremde Software.
Welche Arten von APIs es gibt
Drei, nach der Entfernung geordnet. Eine Bibliothek im eigenen Programm hat eine API, auch wenn niemand sie so nennt. Eine Anwendung auf demselben Rechner bietet eine an, etwa das Betriebssystem. Und über das Netz erreichbare Schnittstellen sind das, was im Alltag gemeint ist.
Die Unterscheidung hat einen praktischen Grund: Je weiter außen die Schnittstelle sitzt, desto mehr gehört in die eigene Fehlerbehandlung. Eine Bibliothek fällt nicht aus; eine fremde Schnittstelle im Netz tut es regelmäßig.
Wie ein Aufruf aufgebaut ist
Aus Anfrage und Antwort, und beide bestehen aus Kopfzeilen und einem Körper. Die Anfrage nennt die Methode, die Adresse und einige Angaben in den HTTP-Headern; die Antwort beginnt mit einem Statuscode und bringt die Nutzdaten mit.
Mehr ist es nicht. Jede Dokumentation einer Schnittstelle beschreibt genau diese beiden Hälften, und wer sie liest, sucht vier Dinge: die Adresse, die Methode, die nötigen Kopfzeilen und die Form der Antwort.
Einen Aufruf auf der Kommandozeile machen
Mit einem Befehl, der die Anfrage und die Antwort vollständig zeigt. Der Schalter -i blendet die Kopfzeilen der Antwort mit ein; ohne ihn sieht man nur den Körper und verliert den Statuscode.
# Eine Rechnung abfragen
curl -i https://api.example.com/v1/rechnungen/4711 \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
HTTP/1.1 200 OK
Content-Type: application/json
{ "nummer": 4711, "betrag": 1190.00, "bezahlt": false }Dieser eine Befehl ist der schnellste Weg, eine fremde Schnittstelle zu prüfen, bevor eine Zeile Programmcode entsteht. Er beantwortet die Frage, ob das Zeichen gilt, ob die Adresse stimmt und ob die Antwort so aussieht wie beschrieben.
Was die Methoden bedeuten
Fünf kommen im Alltag vor, und die letzte Spalte entscheidet über die eigene Fehlerbehandlung.
Methode | Was sie bedeutet | Darf sie wiederholt werden? |
|---|---|---|
GET | Etwas abfragen, ohne es zu verändern | Ja, beliebig oft |
POST | Etwas anlegen oder einen Vorgang auslösen | Nein, sonst entstehen Dubletten |
PUT | Etwas vollständig ersetzen | Ja, das Ergebnis bleibt dasselbe |
PATCH | Einzelne Felder ändern | Kommt auf die Schnittstelle an |
DELETE | Etwas löschen | Ja, beim zweiten Mal gibt es nichts mehr zu löschen |
Daraus folgt die wichtigste Regel beim Anbinden: Ein Aufruf, der wiederholt werden darf, kann nach einem Fehler einfach noch einmal geschickt werden. Bei POST geht das nicht; dort braucht es entweder eine Kennung, mit der die Gegenseite eine Wiederholung erkennt, oder eine Prüfung, ob der Vorgang schon angelegt wurde.
Was die Statuscodes sagen
In welcher Gruppe das Problem liegt. Alles mit 2 am Anfang hat geklappt. Alles mit 4 ist ein Fehler des Aufrufers: Zeichen fehlt, Adresse falsch, Angaben unvollständig, Grenze erreicht. Alles mit 5 ist ein Fehler der Gegenseite. Diese Einteilung bestimmt, was die eigene Anwendung tun soll, denn einen 4er-Fehler zu wiederholen ist sinnlos und einen 5er zu wiederholen ist richtig.
# Dieselbe Adresse, drei Fälle, die jede Anbindung abfangen muss
HTTP/1.1 401 Unauthorized # das Zeichen fehlt oder ist abgelaufen
HTTP/1.1 404 Not Found # die Rechnung gibt es nicht
HTTP/1.1 429 Too Many Requests # die Grenze ist erreicht
Retry-After: 30
# Und der Fall, für den es gar keinen Statuscode gibt:
# die Antwort kommt nicht.Der letzte Fall im Beispiel ist der, den die meisten Anbindungen vergessen: Die Gegenseite antwortet gar nicht. Ohne eine gesetzte Zeitgrenze wartet die eigene Anwendung dann, bis ihr eigener Prozess abläuft, und reicht den Stillstand an die Besucher weiter.
Wie eine API abgesichert wird
Über einen Nachweis und über eine Grenze. Der Nachweis ist ein Schlüssel oder ein Zeichen, bei fremden Zugriffen im Namen eines Nutzers über OAuth; das Zeichen selbst ist oft ein JWT. Die Grenze ist eine Begrenzung der Aufrufe je Zeit, siehe Rate Limiting, damit ein einzelner Konsument den Dienst nicht lahmlegt.
Dazu kommen zwei Regeln, die unabhängig davon gelten. Jede Eingabe wird auf dem Server geprüft, auch wenn die eigene Anwendung sie schon geprüft hat; die fremde Anwendung, die gleich danach anfragt, hat das nämlich nicht getan. Und jeder Zugang bekommt nur die Rechte, die er braucht, siehe Least Privilege.
Warum Versionierung früh zählt
Weil die erste Änderung immer kommt. Wer von Anfang an eine Fassung in der Adresse oder in einer Kopfzeile führt, kann die alte weiterlaufen lassen, während die neue entsteht; wer es nicht tut, steht vor der Wahl zwischen Stillstand und einem Bruch bei allen Nutzern. Dazu gehört eine Ansage, wie lange eine alte Fassung noch bedient wird.
Was eine brauchbare API-Dokumentation enthält
Drei Dinge, die im Alltag über den Erfolg entscheiden. Erstens ein Beispiel je Aufruf, das sich kopieren und ausführen lässt, samt echter Antwort. Zweitens eine vollständige Liste der Fehler mit dem jeweiligen Statuscode und dem, was der Aufrufer dagegen tun kann. Und drittens eine Umgebung zum Ausprobieren, in der nichts kaputtgeht. Eine Schnittstelle ist nur so gut, wie sie sich ohne Rückfrage benutzen lässt.
Was eine API nicht leistet
Sie macht aus zwei Systemen kein eines. Die Schnittstelle überträgt Daten, und alles, was dahinter liegt, bleibt getrennt: zwei Datenbestände, zwei Zeitpunkte, zwei Vorstellungen davon, was ein Kunde ist. Jede Anbindung muss deshalb die Frage beantworten, welche Seite im Streitfall recht hat, und das ist keine technische Frage.
Zweitens verschwindet die Abhängigkeit nicht, sie wechselt nur die Form. Wer eine fremde Schnittstelle benutzt, hat deren Verfügbarkeit, deren Preise und deren Entscheidungen über Fassungen im eigenen Betrieb; ein Anbieter, der seine Schnittstelle abkündigt, erzeugt eine Frist, die niemand im eigenen Haus gesetzt hat. Diese Abhängigkeit gehört in dieselbe Liste wie jede andere, siehe Abhängigkeit.
Wem eine Schnittstelle urheberrechtlich gehört
In Europa ist die Antwort klarer, als die Debatte vermuten lässt. Paragraf 69a Absatz 2 des Urheberrechtsgesetzes stellt fest, dass „Ideen und Grundsätze, die einem Element eines Computerprogramms zugrunde liegen“ nicht geschützt sind, und nennt dabei ausdrücklich „die den Schnittstellen zugrundeliegenden Ideen und Grundsätze“. Geschützt ist allein die Ausdrucksform, also der Code, der die Schnittstelle umsetzt, und eine ausformulierte Dokumentation.
Praktisch heißt das: Welche Aufrufe es gibt, wie sie heißen, welche Angaben sie erwarten und was sie zurückgeben, ist frei. Wer eine fremde Schnittstelle nachbaut, damit seine Software mit der anderen zusammenarbeitet, bewegt sich urheberrechtlich auf sicherem Grund, solange er nicht den fremden Code übernimmt. Paragraf 69e geht noch weiter und erlaubt sogar das Rückübersetzen fremden Codes, wenn es zur Herstellung der Interoperabilität unerlässlich ist, die Informationen nicht anders zu bekommen sind und sich der Eingriff auf die nötigen Teile beschränkt.
In den Vereinigten Staaten war dieselbe Frage Gegenstand eines langen Verfahrens. Der Oberste Gerichtshof entschied am 05.04.2021 mit sechs zu zwei Stimmen, dass die Übernahme von rund 11.500 Zeilen der Java-Schnittstelle durch Google eine zulässige Nutzung war. Ob Schnittstellen überhaupt urheberrechtlich schutzfähig sind, ließ das Gericht ausdrücklich offen; entschieden ist also der Einzelfall und nicht die Grundsatzfrage.
Drei Dinge bleiben trotzdem heikel, und sie haben mit dem Urheberrecht nichts zu tun. Der Name der fremden Schnittstelle ist meist eine Marke. Die Daten dahinter können eigene Rechte haben. Und die Nutzungsbedingungen, die jemand beim Anlegen eines Zugangs bestätigt, gelten vertraglich, auch wenn sie mehr verbieten, als das Urheberrecht hergibt.
Nachzulesen ist die Regel in Paragraf 69a UrhG; die Ausnahme zur Rückübersetzung steht einen Paragrafen weiter in 69e.
Eine fremde Schnittstelle anbinden, ohne beim ersten Ausfall stehenzubleiben
Mit vier Vorkehrungen, die zusammengehören. Eine Zeitgrenze für jeden Aufruf, damit ein stilles Gegenüber nicht die eigene Anwendung blockiert. Eine Wiederholung mit wachsendem Abstand, aber nur für die Fälle, in denen sie erlaubt ist. Ein Zwischenspeicher für Antworten, die sich selten ändern, siehe Cache. Und eine Entscheidung, was die eigene Anwendung anzeigt, wenn gar nichts kommt: eine alte Zahl mit Zeitstempel ist fast immer besser als eine Fehlerseite.
Dazu gehört die Protokollierung jedes fehlgeschlagenen Aufrufs mit Statuscode und Zeitpunkt, siehe Logging. Ohne sie ist die Frage, ob der Anbieter ein Problem hat oder die eigene Anbindung, nicht zu beantworten, und genau diese Frage kommt irgendwann.
Eine eigene Schnittstelle für Dritte öffnen
Mit drei Entscheidungen vor der ersten Zeile Code. Wer darf zugreifen, und wie weist er sich aus? Wie viele Aufrufe sind je Konsument frei, und was passiert darüber hinaus? Und wie lange gilt eine Zusage, bevor sie geändert werden darf? Diese drei Antworten gehören in die Dokumentation und nicht in ein späteres Gespräch, denn jeder, der die Schnittstelle benutzt, richtet sich darauf ein.
Praktisch bewährt hat sich, mit wenigen Aufrufen zu beginnen und sie zu erweitern. Eine Schnittstelle lässt sich leicht ergänzen und schwer verkleinern: Jeder Aufruf, den jemand einmal benutzt hat, ist ein Versprechen für Jahre.
Woher der Begriff kommt
Aus den sechziger Jahren, lange vor dem Web. Gemeint war damals die Schnittstelle zwischen einem Programm und einer Bibliothek auf demselben Rechner; das Wort „Application“ stand für das Anwendungsprogramm und nicht für eine App. Erst in den zweitausender Jahren verschob sich die übliche Bedeutung auf Schnittstellen über das Netz, und heute meint „API“ im Alltag fast immer diese.
Die alte Bedeutung ist trotzdem nicht verschwunden, und das führt regelmäßig zu Missverständnissen: Wenn in einer Stellenanzeige „Erfahrung mit APIs“ steht, kann beides gemeint sein. Die Rückfrage lohnt sich, denn die beiden Welten haben außer dem Namen wenig gemeinsam.