Eine API ist der Vertrag, den ein Client nutzt, um ein System zur Ausführung einer Aufgabe zu veranlassen. In einem Vorstellungsgespräch muss dieser Vertrag die wichtigsten Benutzeraktionen – wie das Erstellen, Abrufen, Bearbeiten, Löschen und Teilen einer Notiz – einfach und vorhersehbar gestalten. Zudem muss er problematische Mehrdeutigkeiten vermeiden, etwa zwei verschiedene Endpunkte, die eine Notiz zwar „irgendwie“ aktualisieren, sich bei gleicher Eingabe jedoch unterschiedlich verhalten. Veranschaulichen wir diesen Vertrag anhand einer minimalen Notizen-App, bei der ein Mobil- oder Web-Client mit einem Backend-Dienst kommuniziert, der die Notizen in einer Datenbank speichert.
Bei diesem grundlegenden Entwurf sendet der Client eine HTTP-Anfrage an den API-Dienst; dieser validiert die Anfrage und wendet die Vertragsregeln an, während die Datenbank die Notizdatensätze speichert, sodass zukünftige Lesezugriffe denselben Zustand liefern. Entscheidend ist hierbei die Eigenverantwortung der Komponenten: Der Client wählt den Aufruf aus, der API-Dienst entscheidet über Zulässigkeit und Schreibvorgänge, und die Datenbank persistiert das Ergebnis, damit es für die nächste Anfrage verfügbar ist. Diese Struktur werden wir später besonders hervorheben, wenn ein einzelner Server nicht mehr ausreicht.
Die einfachste funktionale API benennt Ressourcen eindeutig und verknüpft jeden Endpunkt mit genau einer Benutzeraktion sowie einer spezifischen Objektstruktur. Eine Notiz ist ein Objekt mit id, ownerUserId, title, body und Zeitstempeln; die Freigabefunktion ergänzt eine Regel, die es einem anderen Benutzer ermöglicht, die Notiz – abhängig von der jeweiligen Berechtigung – zu lesen oder zu bearbeiten. Auf diese Weise lässt sich der Kernablauf mit einer kleinen Anzahl von Endpunkten abbilden, ohne zusätzliche Verben oder überladene Bedeutungen einführen zu müssen. Die Zuordnung jedes Endpunkts zu einem Lese- oder Schreibvorgang sorgt dafür, dass der API-Vertrag auch bei hoher Komplexität übersichtlich bleibt. Ordnen wir diese Endpunkte nun dem Basisdienst sowie den Lese- und Schreibvorgängen der Datenbank zu.