Web-Architektur · 9 Min.
Zuletzt geprüft: 6. Oktober 2026
Themenfeld: CMS, Static Site oder Web-App: Architektur für digitale Projekte wählen
Inhalt · 11 Abschnitte
API-first Architektur: Wann eine API zum Kern des Systems gehört
Eine API gehört nicht automatisch zur Architektur, nur weil ein System Daten über HTTP austauscht. Entscheidend ist, ob mehrere Oberflächen, Dienste oder Prozesse zuverlässig auf dieselben Fähigkeiten und Daten zugreifen müssen – und ob diese Zugriffe unabhängig voneinander weiterentwickelt werden sollen. Für Geschäftsführung, Produktverantwortliche und technische Leitung bedeutet die Entscheidung deshalb mehr als die Wahl eines technischen Stils: Sie legt fest, wo Regeln liegen, wer Änderungen verantwortet und wie neue Verbraucher angebunden werden. Eine API-first Architektur lohnt sich, wenn der Vertrag zwischen diesen Teilen eine stabile Grenze bilden soll. Sie ist meist unnötig, wenn eine einzelne Oberfläche eng mit einem überschaubaren Backend verbunden bleibt. Maßgeblich sind die tatsächlichen Nutzungsszenarien, die Änderungsabhängigkeiten und die Kosten, einen API-Vertrag dauerhaft zu betreiben.
Kurz gesagt
API-first bedeutet, die Schnittstelle als verbindlichen Vertrag zu entwerfen, bevor einzelne Verbraucher daran angepasst werden. Das lohnt sich bei mehreren unabhängigen Oberflächen oder Integrationen, klar getrennten Zuständigkeiten und Daten, die kontrolliert geteilt werden müssen. Eine API erzeugt aber auch Versionierungs-, Sicherheits-, Dokumentations- und Betriebsaufwand. Wenn nur eine Oberfläche auf ein einfaches Backend zugreift und beide gemeinsam geändert werden, kann eine direkte Kopplung die angemessenere Lösung sein.
Ausgangslage
In vielen Systemen entsteht eine API zuerst als technische Verbindung: Ein Frontend benötigt Daten, also wird ein Endpoint ergänzt. Solange ein einzelner Verbraucher existiert, lässt sich manches implizit halten. Backend und Oberfläche können gemeinsam angepasst werden; Fehler fallen im selben Entwicklungsprozess auf.
Die Lage ändert sich, wenn eine zweite Oberfläche, eine mobile App, ein Partnerdienst oder ein Automatisierungsprozess dieselben Daten und Funktionen benötigt. Dann ist nicht mehr nur die Verbindung relevant. Die Verbraucher müssen wissen, welche Felder verfügbar sind, welche Eingaben gültig sind, wie Fehler aussehen und was sich bei einer Änderung ändert.
Ohne vereinbarten Vertrag entsteht die Schnittstelle trotzdem – nur informell. Ein Verbraucher verlässt sich auf Felder oder Abläufe, die nie als stabil zugesagt wurden. Eine interne Änderung kann dadurch mehrere Teile des Systems gleichzeitig brechen. API-first macht diese Abhängigkeiten sichtbar und behandelt den Vertrag als Teil des Produkt- und Systemdesigns.
Das bedeutet nicht, dass jede Funktion öffentlich sein oder jedes System in einzelne Dienste zerlegt werden muss. Eine API kann intern bleiben und trotzdem eine klare Grenze zwischen Oberfläche und Geschäftslogik bilden. Ebenso kann ein gut abgegrenztes System als Monolith betrieben werden. API-first beschreibt zunächst, wie Schnittstellen geplant und genutzt werden, nicht zwingend, wie viele Server oder Anwendungen entstehen.
Entscheidungskriterien
Wie viele unabhängige Verbraucher gibt es?
Zählen Sie nicht nur sichtbare Websites. Berücksichtigen Sie Apps, interne Werkzeuge, Datenimporte, Partnerintegrationen und automatisierte Prozesse. Entscheidend ist, ob diese Verbraucher unabhängig voneinander entwickelt oder betrieben werden.
Eine API wird architektonisch relevant, wenn mehrere Verbraucher dieselbe Geschäftslogik nutzen sollen, ohne direkt an die interne Datenbank oder an die Implementierung des Backends gekoppelt zu sein. Gibt es nur eine Oberfläche und einen gemeinsamen Änderungsprozess, ist der Nutzen einer zusätzlichen Vertragsschicht geringer.
Welche Regeln müssen zentral bleiben?
Wenn Berechtigungen, Validierung, Berechnung oder Freigabe in mehreren Oberflächen identisch funktionieren müssen, sollten diese Regeln nicht in jede Oberfläche kopiert werden. Eine API kann sie an einer Stelle verfügbar machen und damit für alle Verbraucher vereinheitlichen.
Die API darf dabei nicht bloß Datenbanktabellen nach außen spiegeln. Sie sollte die fachlichen Vorgänge abbilden, die ein Verbraucher tatsächlich ausführen darf. Sonst wird die interne Datenstruktur selbst zum Vertrag – und spätere Änderungen daran werden unnötig riskant.
Wie unabhängig müssen Änderungen sein?
Fragen Sie, ob Backend und Verbraucher gemeinsam ausgerollt werden können. Wenn eine neue Version der Oberfläche nur mit einer gleichzeitig angepassten Backend-Version funktioniert, ist die Schnittstelle nicht wirklich entkoppelt.
Ein stabiler Vertrag ermöglicht getrennte Änderungen, aber er verlangt Rücksicht auf bestehende Verbraucher. Dazu gehören Kompatibilitätsregeln, ein klarer Umgang mit nicht mehr unterstützten Versionen und Tests, die den Vertrag prüfen. Je häufiger oder unabhängiger Änderungen erfolgen, desto wichtiger werden diese Vorkehrungen.
Welche Sicherheits- und Betriebsanforderungen gelten?
Eine API ist eine zusätzliche Angriffs- und Fehlerfläche. Klären Sie, wie Identität und Berechtigungen geprüft werden, welche Daten ein Verbraucher sehen darf, wie Eingaben validiert werden und wie Aufrufe begrenzt oder protokolliert werden. Auch Verfügbarkeit, Fehlerbehandlung und Überwachung müssen zum Anwendungsfall passen.
Eine interne API ist nicht automatisch sicher, nur weil sie nicht öffentlich dokumentiert ist. Umgekehrt muss ein API-Vertrag nicht bedeuten, dass jeder Endpunkt für externe Systeme zugänglich ist. Zugriff, Zielgruppe und Datenumfang gehören in die Architekturentscheidung.
Lässt sich der Vertrag verständlich beschreiben?
Ein belastbarer Vertrag legt Methoden, Pfade, Parameter, Datentypen, Fehlerfälle und Berechtigungen fest. Er sollte für Produzenten und Verbraucher prüfbar sein. Eine OpenAPI-Beschreibung kann bei HTTP-Schnittstellen dabei helfen, Erwartungen sichtbar zu machen. Sie ersetzt weder fachliche Entscheidungen noch Tests.
API-first in der Praxis
API-first heißt nicht, jedes Detail vorab vollständig festzuschreiben. Es heißt, die Schnittstelle gemeinsam mit dem Anwendungsfall zu entwerfen und Änderungen nachvollziehbar zu behandeln. Dazu gehört zunächst die Frage, welche fachliche Fähigkeit angeboten wird und welcher Verbraucher sie benötigt.
Ein vereinfachter OpenAPI-Ausschnitt zeigt, wie ein Endpunkt, seine Parameter und die Antwort als Vertrag beschrieben werden können. Das Beispiel ist generisch und bildet keine konkrete Projekt-API ab.
openapi: 3.1.0
info:
title: Katalog-API
version: 1.0.0
paths:
/v1/items:
get:
summary: Katalogeinträge abrufen
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
in: query
required: false
schema:
type: string
responses:
'200':
description: Ergebnisliste
content:
application/json:
schema:
type: object
required: [items]
properties:
items:
type: array
items:
$ref: '#/components/schemas/Item'
nextCursor:
type: [string, 'null']
components:
schemas:
Item:
type: object
required: [id, name]
properties:
id:
type: string
name:
type: string
Der Vertrag macht unter anderem sichtbar, dass die Ergebnisliste begrenzt werden kann und welche Eigenschaften eines Eintrags zugesagt sind. In einem produktiven Vertrag müssten außerdem die tatsächlich relevanten Fehlerantworten, Berechtigungen und fachlichen Einschränkungen beschrieben werden. Die konkrete Form sollte aus dem Nutzungsszenario folgen, nicht aus einer möglichst umfangreichen Spezifikation.
Versionierung ohne unnötige Parallelwelten
Versionierung schützt Verbraucher vor unangekündigten, inkompatiblen Änderungen. Sie sollte aber nicht dazu führen, für jede kleine Anpassung eine neue API-Version zu veröffentlichen.
Änderungen wie ein optionales zusätzliches Feld sind häufig kompatibel, sofern Verbraucher unbekannte Felder tolerieren. Werden Felder entfernt, umbenannt oder in ihrer Bedeutung geändert, kann das bestehende Verbraucher brechen. Solche Änderungen brauchen eine geplante Migration und gegebenenfalls eine neue Version.
Eine Version im URL-Pfad, etwa /v1/, ist leicht sichtbar und verständlich. Andere Versionierungsformen sind ebenfalls möglich. Wichtiger als die konkrete Schreibweise sind klare Regeln: Was gilt als inkompatible Änderung? Wie lange bleibt eine alte Version verfügbar? Wie werden Verbraucher informiert und ihre Nutzung geprüft? Ohne diese Regeln ist die Versionsnummer nur Dekoration.
Szenarien: Wann API-first passt
Mehrere Oberflächen oder eigenständige Verbraucher
Wenn eine Web-Oberfläche und eine App dieselben Funktionen benötigen, kann ein gemeinsamer API-Vertrag die Geschäftslogik zentral halten. Die Oberflächen bleiben eigenständige Verbraucher, statt eigene Zugriffe auf die Datenhaltung aufzubauen. Änderungen an einem Verbraucher müssen dann nicht automatisch Änderungen an allen anderen auslösen.
Integrationen und Datenprodukte
Eine API kann sinnvoll sein, wenn Partner oder interne Systeme Informationen kontrolliert austauschen. Sie schafft einen definierten Zugriff statt einer direkten Kopplung an Tabellen, Dateien oder interne Implementierungen. Dafür müssen Datenumfang, Berechtigungen und Fehlerverhalten ausdrücklich festgelegt werden.
Ein Backend für eine einzelne, eng gekoppelte Oberfläche
Wenn eine Anwendung nur eine Oberfläche hat, Funktionen und Oberfläche gemeinsam ausgeliefert werden und keine weiteren Verbraucher absehbar sind, kann eine zusätzliche API-Schicht unnötige Komplexität erzeugen. Eine interne Modulgrenze oder direkte serverseitige Verarbeitung kann ausreichend sein. Entscheidend ist, ob die Grenze einen konkreten Änderungs- oder Integrationsbedarf löst.
Fachlich stark geregelte Abläufe
Wenn Daten vor der Veröffentlichung geprüft oder freigegeben werden müssen, sollte die Schnittstelle diese Zustände und erlaubten Aktionen abbilden. Ein bloßer Lesezugriff auf alle Datensätze kann die fachliche Kontrolle umgehen. Hier zählt, dass der Vertrag nicht nur Datenfelder, sondern auch zulässige Vorgänge und Zustandsübergänge berücksichtigt.
Typische Fehler
- API-first mit API-only verwechseln. Eine API kann ein Teil der Architektur sein, ohne dass jede interne Komponente über HTTP kommunizieren muss.
- Endpunkte um Tabellen herum entwerfen. So werden Datenbankstrukturen nach außen festgeschrieben, statt fachliche Fähigkeiten bereitzustellen.
- Den Vertrag nur dokumentieren. Wenn Spezifikation, Implementierung und Tests auseinanderlaufen, ist die Dokumentation keine verlässliche Grundlage.
- Versionierung zu spät planen. Sobald unabhängige Verbraucher existieren, kann eine inkompatible Änderung mehrere Systeme gleichzeitig treffen.
- Sicherheit als nachgelagerte Aufgabe behandeln. Zugriff, Rollen und zulässige Daten gehören bereits in den Entwurf der Schnittstelle.
- Jede Funktion als API-Projekt behandeln. Eine Schnittstelle ohne eigenständigen Verbraucher oder klaren Entkopplungsnutzen verursacht Pflegeaufwand ohne entsprechenden Nutzen.
Praxisbeispiel
Cardfolio ist als API-first Sammlungsplattform aufgebaut. Die Web-Oberfläche greift über eine versionierte API auf das Backend zu, statt direkt mit der Datenbank zu kommunizieren. Das Backend nutzt Fastify und Zod; PostgreSQL bildet die Datenhaltung. Zu den weiteren Bestandteilen gehören JWT, Rate-Limits und eine idempotente Katalog-Synchronisation. Das Beispiel zeigt den Nutzen einer klaren Grenze: Die Oberfläche arbeitet mit einem festgelegten Vertrag, während Datenhaltung und Backend-Logik hinter dieser Grenze bleiben. Cardfolio ansehen
Ein anderes Integrationsmuster zeigen Affiliate-Backends: Bei eisenross importiert ein eigenes PHP/MySQL-Backend Awin-Feeds, klassifiziert Produkte regelbasiert und erstellt ein Ranking. Produkte werden erst nach Freigabe öffentlich. Bei Garten 1x1 ergänzt ein eigenes PHP/MySQL-Backend die statische Website und ermöglicht die Freigabe im Admin. Solche Beispiele belegen nicht, dass jedes Backend eine externe API benötigt. Sie zeigen, dass Oberfläche, Verarbeitung und Freigabe als getrennte Aufgaben modelliert werden können; ob dafür eine API die passende Grenze ist, hängt von den Verbrauchern und Abläufen ab. eisenross ansehen · Garten 1x1 ansehen
Empfehlung
- Wenn mehrere unabhängig entwickelte Oberflächen oder Dienste dieselbe Geschäftslogik benötigen, entwerfen Sie einen gemeinsamen API-Vertrag.
- Wenn eine Oberfläche nur Daten lesen oder ändern muss, die auch andere Verbraucher benötigen, prüfen Sie eine versionierte API als zentrale Zugriffsschicht.
- Wenn Backend und Oberfläche gemeinsam geändert und ausgeliefert werden und keine weiteren Verbraucher bestehen, halten Sie die Architektur zunächst einfacher.
- Wenn externe Partner zugreifen, legen Sie Berechtigungen, Datenumfang, Fehlerverhalten und Betriebsverantwortung vor der Umsetzung fest.
- Wenn Sie eine API bereits betreiben, definieren Sie Regeln für kompatible Änderungen, Tests und den Umgang mit alten Versionen, bevor weitere Verbraucher hinzukommen.
- Wenn die fachliche Logik auf mehrere Systeme verteilt ist, klären Sie zuerst Zuständigkeiten und Datenmodell. Eine API allein löst keine unklare Systemverantwortung.
Checkliste
Häufige Fragen
Bedeutet API-first automatisch Headless?
Nein. API-first beschreibt die Bedeutung und Planung der Schnittstelle. Headless bezeichnet eine stärkere Trennung von Präsentationsschicht und Backend. Ein System kann eine API-first Architektur nutzen, ohne dass sämtliche Ausgaben über ein separates Frontend erfolgen. Mehr zur Abwägung: Monolith oder Headless.
Muss jede interne Funktion einen eigenen Endpoint bekommen?
Nein. Endpunkte sollten konkrete Verbraucher und fachliche Vorgänge unterstützen. Eine kleinteilige Schnittstelle ohne entsprechenden Bedarf erschwert Änderungen und erhöht den Betriebsaufwand.
Wann sollte eine API versioniert werden?
Sobald unabhängige Verbraucher auf einen stabilen Vertrag angewiesen sind, sollten Änderungen geregelt sein. Eine sichtbare Versionsnummer ist besonders dann relevant, wenn inkompatible Änderungen nicht gemeinsam mit allen Verbrauchern ausgerollt werden können.
Ist eine dokumentierte API automatisch stabil?
Nein. Stabilität entsteht durch klare Kompatibilitätsregeln, Tests, kontrollierte Änderungen und einen verantworteten Betrieb. Eine Spezifikation macht Erwartungen sichtbar, garantiert aber nicht, dass die Implementierung sie einhält.
Weiterführend
- Monolith oder Headless: Warum Architektur kein Glaubenskrieg sein sollte
- Headless CMS oder klassisches CMS: Vorteile, Nachteile und Entscheidungskriterien
- WordPress REST API richtig einsetzen: Architektur statt Endpoint-Sammlung
- Payload CMS für Datenprodukte: Typisierte Inhalte, APIs und editorische Kontrolle
Verwandte Beiträge
Web-Architektur · 9 Min.
CMS für Kunden: Inhalte bearbeiten mit passender ArchitekturVergleichen Sie WordPress, Headless-CMS und Git-Workflows für Kundenredaktionen. Mit Kriterien für Rollen, Freigaben, Vorschau und statische Auslieferung.
Web-Architektur · 9 Min.
WordPress vs. Ghost: Welche Plattform passt zu Ihrem Content-Modell?WordPress oder Ghost? Entscheiden Sie anhand von Redaktion, Datenmodell, Erweiterbarkeit und Betrieb, welche Plattform zu Ihrer Content-Plattform passt.
Web-Architektur · 10 Min.
WordPress vs. Payload CMS: Welches System passt besser?WordPress oder Payload CMS? Vergleichen Sie Datenmodell, Redaktion, APIs und Betrieb – und treffen Sie eine passende Systementscheidung für Ihr Unternehmen.
Field Notes · 6 Min.
Field Note: Was in eine vernünftige Projektübergabe gehörtBei einer Projektübergabe reichen Login, Repository und ein „läuft“ nicht. Ich beschreibe, warum nachvollziehbare Entscheidungen und Betriebswissen entscheidend sind.