Eine API, Application Programming Interface, ist eine definierte Schnittstelle, über die ein Programm die Funktionen oder Daten eines anderen nutzen kann. Sie beschreibt, welche Anfragen möglich sind, welche Angaben dafür nötig sind und welche Antworten zurückkommen.
Eine API ist ein Vertrag
Der wichtigste Gedanke ist, dass eine veröffentlichte API kein Implementierungsdetail ist, sondern eine Zusage. Sobald ein anderes System sie nutzt, hängt dessen Funktionsfähigkeit daran. Eine Änderung, die intern trivial wirkt — ein umbenanntes Feld, ein anderer Datentyp, eine strengere Prüfung — kann bei jedem Nutzer der Schnittstelle einen Ausfall verursachen. Diese Verpflichtung ist der eigentliche Unterschied zwischen einer internen Funktion und einer API.
Was eine Schnittstelle beschreibt
Vollständig beschrieben ist eine API erst, wenn vier Dinge festgelegt sind: welche Vorgänge es gibt, welche Angaben jeder Vorgang erwartet, welche Antworten er liefert, und welche Fehler auftreten können. Der vierte Punkt wird am häufigsten vernachlässigt und ist in der Praxis der wichtigste — ein aufrufendes System muss wissen, wie es auf einen Fehler reagieren soll, und das kann es nur, wenn die Fehler definiert und unterscheidbar sind.
Versionierung
Weil eine API ein Vertrag ist, brauchen Änderungen einen geordneten Weg. Ergänzungen sind unkritisch: Ein neues, optionales Feld stört niemanden. Änderungen an Bestehendem sind es nicht. Der übliche Umgang ist eine Versionierung, bei der die alte Fassung erreichbar bleibt, während die neue eingeführt wird, mit einer angekündigten Frist für den Wechsel. Wer stattdessen still ändert, verlagert die Kosten auf alle Nutzer der Schnittstelle gleichzeitig.
Dokumentation ist Teil des Produkts
Eine Schnittstelle ohne Dokumentation ist praktisch unbenutzbar, weil jeder Nutzer ihr Verhalten durch Ausprobieren rekonstruieren muss — und dabei zwangsläufig auch undokumentierte Eigenheiten als Zusage missversteht. Nützlich ist eine Dokumentation, die neben der formalen Beschreibung konkrete Beispiele für Anfragen und Antworten enthält, einschliesslich der Fehlerfälle.
Was eine gute von einer brauchbaren unterscheidet
Eine brauchbare API funktioniert. Eine gute ist zusätzlich vorhersagbar: gleichartige Vorgänge folgen demselben Muster, Benennungen sind konsistent, Fehler sehen überall gleich aus, und das Verhalten bei Wiederholung derselben Anfrage ist definiert. Diese Vorhersagbarkeit senkt den Aufwand auf der aufrufenden Seite mehr als jede zusätzliche Funktion.
Praktische Konsequenz
Vor der Veröffentlichung einer Schnittstelle lohnt die Frage, ob man mit ihr in zwei Jahren noch leben möchte. Was einmal veröffentlicht und genutzt wird, lässt sich nur mit Aufwand wieder ändern — und der Aufwand fällt bei allen an, nicht nur beim Anbieter.