Spec-First API-Entwicklung

In vielen Backend-Teams beginnt eine neue API mit dem ersten Spring-Controller oder dem ersten Express-Router. Zuerst entsteht der Code, danach wird die Spec daraus generiert. Spec-First setzt genau früher an. Die OpenAPI-Spezifikation wird zuerst entworfen, mit den Konsumenten abgestimmt und dient anschließend als Grundlage für die Implementierung.

Das wirkt zunächst wie eine kleine Änderung im Ablauf. In der Praxis verändert es jedoch die API-Qualität, die Zusammenarbeit und die Geschwindigkeit deutlich. Wer Spec-First konsequent nutzt, ändert nicht nur die Reihenfolge im Workflow, sondern verschiebt auch den Zeitpunkt, an dem zentrale API-Entscheidungen getroffen werden.

Die Begriffs-Karte rund um Spec-First

Rund um Spec-First werden mehrere Begriffe verwendet, die im Alltag oft ähnlich klingen, aber unterschiedliche Schwerpunkte setzen.

In der täglichen Arbeit sind die Unterschiede oft weniger wichtig als in Architektur-Diskussionen. Spec-First, Design-First und Contract-First beschreiben meist dasselbe technische Vorgehen, nur aus unterschiedlichen Perspektiven. API-First ist breiter gefasst und beschreibt die organisatorische Haltung dahinter, in der APIs als eigenständige Produkte mit eigenen Roadmaps geplant werden.

Welcher Begriff sich im Team durchsetzt, hängt oft davon ab, wer den Ansatz einführt. Architekten sprechen meist von Spec-First, Produkt-Manager eher von API-First. Compliance-orientierte Teams in Banking oder Healthcare nutzen häufig Contract-First, weil dort der Vertragscharakter wichtiger ist als die reine Spec-Datei.

Wo der wirkliche Unterschied zwischen Spec-First und API-First liegt

Spec-First und API-First werden in Diskussionen oft vermischt, beschreiben aber zwei unterschiedliche Ebenen. Spec-First ist eine technische Disziplin im Workflow eines API-Projekts. API-First ist eine organisatorische Grundhaltung, bei der APIs als eigenständige Produkte mit Roadmaps, Stakeholdern und Lebenszyklen geführt werden.

Der Unterschied lässt sich einfach prüfen. Ein Unternehmen kann API-First arbeiten, ohne Spec-First umzusetzen. Es behandelt APIs strategisch als Produkte, generiert die OpenAPI-Specs aber weiterhin aus dem Backend-Code. Auf Workflow-Ebene bleibt es also Code-First. Umgekehrt kann ein einzelnes Team Spec-First arbeiten, obwohl die Organisation APIs weiterhin als Anhängsel von Anwendungen plant.

In Architektur-Diskussionen hilft die Frage nach der Ebene. Geht es um Verantwortlichkeiten, Roadmaps, Investitionsentscheidungen und API-Governance, spricht man über API-First. Geht es um Tooling, CI-Pipelines, Code-Generation und den Zeitpunkt, an dem die OpenAPI-Datei entsteht, geht es um Spec-First.

Beide Ansätze ergänzen sich, hängen aber nicht zwingend voneinander ab. Ein etabliertes Setup kombiniert API-First als organisatorische Strategie mit Spec-First als technischer Umsetzung. Wer mit Spec-First startet, schafft nebenbei Strukturen, die später eine API-First-Strategie tragen können. Wer dagegen API-First ausruft, ohne Spec-First in den Teams zu verankern, riskiert eine Strategie ohne operative Wirkung.

Was Spec-First eigentlich heißt

Spec-First bedeutet, dass zuerst die OpenAPI-Spezifikation entsteht und sie anschließend in Code umgesetzt wird. Die Spec ist damit nicht das Ergebnis der Backend-Arbeit, sondern ihr Ausgangspunkt. Was nach einer kleinen Änderung in der Reihenfolge klingt, verlagert im Team Verantwortung und Entscheidungszeitpunkte.

Beim Code-First-Ansatz wird zuerst der Backend-Code geschrieben, oft mit Annotations wie @ApiOperation oder @Schema. Daraus generiert ein Tool im Build-Prozess die OpenAPI-Spec. Das ist am Anfang schnell, hat aber einen klaren Nachteil. Konsumenten sehen die API erst, wenn sie im Backend bereits weitgehend umgesetzt ist. Änderungen erfolgen dadurch später und werden teurer.

Spec-First dreht diese Reihenfolge um. Ein API-Designer, häufig aus dem Architektur-Team, erstellt die Spec direkt in YAML oder JSON. Danach wird die Spec mit den Konsumenten geprüft, bevor Backend-Code entsteht. Erst nach diesem Schritt wird das Backend nach der Spec implementiert, oft unterstützt durch generierte Server-Stubs.

OpenAPI ist dafür das Standard-Format. Gearbeitet wird meist in einem YAML-Editor mit Linter-Plugin oder in einer spezialisierten Plattform wie api-portal.io oder Stoplight Studio. Die Spec liegt im Git-Repo, durchläuft denselben PR-Prozess wie der Code und wird über Linter, Validierungs-Pipelines und Contract Tests abgesichert.

Mit Spec-First verändert sich auch die Arbeitskultur. Der Backend-Entwickler ist nicht mehr automatisch der Erste, der die API beschreibt. Die Spezifikation wird nun statt vom Backend-Entwickler von einem API-Designer oder Architekt erstellt, meist in enger Abstimmung mit den späteren Konsumenten.

Diese Verschiebung erklärt, warum Spec-First nicht in jedem Team sofort gut ankommt. Der Ansatz verlangt eine Design-Phase, die in agilen Setups zunächst wie zusätzlicher Aufwand wirkt. Dass diese Phase später Zeit spart, weil Änderungen an der Spec günstiger sind als Änderungen am Backend-Code, zeigt sich oft erst nach dem zweiten oder dritten API-Projekt.

Der Spec-First-Workflow in fünf Schritten

Ein Spec-First-Workflow lässt sich gut in fünf Schritte aufteilen. Jeder Schritt hat eigene Inputs, Outputs und Verantwortlichkeiten.

1. Anforderungen sammeln. Dieser Schritt kommt vor der technischen Modellierung. Wer nutzt die API, welche Use Cases sind wichtig, welche Daten sollen ausgetauscht werden? Im Mittelpunkt stehen hier Konsumenten und Produkt-Verantwortliche, nicht zuerst das Backend-Team.
2. Spec entwerfen. Endpoints, Schemas und Auth-Mechanismen werden in OpenAPI beschrieben. Der API-Designer arbeitet dafür meist in einem YAML-Editor mit Linter-Plugin oder in einer spezialisierten Plattform. Die Versionierung über Git läuft von Anfang an mit.
3. Mit Konsumenten reviewen. Bevor die Backend-Implementierung startet, wird die Spec gemeinsam geprüft. Mock-Server aus der Spec ermöglichen erste Test-Calls und frühes Feedback. Breaking Changes fallen in dieser Phase auf, wenn Korrekturen noch vergleichsweise günstig sind.
4. Backend implementieren. Erst nach dem Spec-Approval beginnt die Backend-Arbeit. Server-Stubs aus der Spec liefern den Skelett-Code, der anschließend mit Geschäftslogik gefüllt wird. Die Spec bleibt dabei die Referenz, gegen die getestet wird.
5. Continuous Validation. In der CI prüft ein Linter die Spec. Contract Tests vergleichen die Spec mit dem tatsächlichen Backend-Verhalten, während ein Versionierungs-Mechanismus Breaking Changes sichtbar macht.

Die Reihenfolge ist nicht vollständig starr. In der Praxis wechseln Teams häufig zwischen Schritt 2 und 3, weil Konsumenten-Feedback Anpassungen an der Spec auslöst. Schritt 5 läuft kontinuierlich mit, sobald die Spec im Repo liegt.

Was Spec-First konkret bringt

Der erste Effekt zeigt sich beim Tempo. Sobald die Spec steht, können Konsumenten anhand eines Mock-Servers entwickeln, lange bevor das Backend fertig ist. In Projekten mit mehreren konsumierenden Teams entsteht dadurch ein Vorlauf von mehreren Wochen, der im Code-First-Modell oft verloren geht. Im selben Schritt fallen Breaking Changes früher auf. Ein umbenanntes Feld oder ein neuer Pflichtparameter wird im Design-Review sofort sichtbar, während Code-First-Projekte dasselbe Problem häufig erst im Konsumenten-Roll-out bemerken, wenn die Backend-Arbeit fast abgeschlossen ist und Änderungen deutlich teurer werden.

Der zweite Effekt liegt auf der Konsistenz-Seite. Aus einer sauberen OpenAPI-Spec lassen sich Server-Stubs, Client-SDKs in mehreren Sprachen und Validierungs-Schemas verlässlich generieren, während im Code-First-Workflow die generierte Spec oft lückenhaft bleibt, weil Annotations fehlen oder uneinheitlich gepflegt werden. Hinzu kommt der Effekt auf die Team-Koordination. Eine zentrale Spec dient als gemeinsame Referenz für Backend-Team, Konsumenten, Tester und Doku-Schreiber, und Diskussionen drehen sich dadurch um den API-Vertrag selbst, nicht darum, welche Annotation in welcher Datei fehlt.

Ein weiterer Vorteil zeigt sich erst langfristig. Wer mehrere APIs mit demselben Spec-First-Workflow entwickelt, schafft eine konsistente Spec-Landschaft mit einheitlichen Naming-Konventionen, Auth-Mustern und Versionierungs-Regeln. Diese Konsistenz fällt bei einer einzelnen API kaum auf. Für Konsumenten, die mehrere APIs derselben Organisation integrieren, macht sie jedoch den Unterschied zwischen einer geplanten und einer historisch gewachsenen API-Landschaft.

Wo Spec-First Reibung erzeugt

Spec-First funktioniert nicht automatisch. Während der Einführung dominieren drei Reibungspunkte. Eine OpenAPI-Spec von Hand zu schreiben dauert zunächst länger als ein paar Annotations, und Teams ohne Erfahrung empfinden das schnell als Verzögerung. Der Aufwand zahlt sich später aus, wird aber oft erst nach drei bis sechs Monaten spürbar. Hinzu kommt, dass nicht jedes Backend-Framework aus OpenAPI-Specs sauberen Code erzeugt. Spring REST und FastAPI sind gut unterstützt, während weniger verbreitete Stacks wie Quarkus oder Phoenix oft schwächere Generatoren mitbringen und der manuelle Anpassungsaufwand höher bleibt als erwartet. Schwerer wiegt häufig die Skepsis im Team. Manche Backend-Entwickler empfinden ihre Rolle in der Spec-Erstellung als kleiner, wenn ein API-Designer oder Architekt die Spec vorbereitet. Wer Spec-First einführt, sollte deshalb klar machen, dass die Backend-Implementierung anspruchsvoll und zentral bleibt und nur auf einer besser abgestimmten Grundlage beginnt.

Im laufenden Betrieb verschiebt sich der Fokus auf zwei andere Reibungen. Ohne aktive Pflege entfernen sich Spec und tatsächliches Backend-Verhalten voneinander. Der Backend-Code wird angepasst, die Spec bleibt unverändert, und nach drei Monaten beschreibt sie eine API-Version, die es so nicht mehr gab. Dann wirkt Spec-First wie zusätzlicher Verwaltungsaufwand statt wie ein Qualitätsgewinn. Genauso heikel ist die Realitätslücke der Mock-Server. Sie liefern Antworten, die syntaktisch zur Spec passen, aber nicht das Verhalten des echten Backends abbilden. Race Conditions, Konsistenz-Garantien oder Performance-Eigenschaften bleiben dadurch unsichtbar. Wer Mock-Server als einzige Testquelle nutzt, riskiert Integrations-Bugs in Production. Sinnvoller ist es, Mock-Server in der Frühphase einzusetzen und anschließend so früh wie möglich anhand eines echten Backends zu testen.

Wann Spec-First nicht die richtige Wahl ist

Spec-First passt nicht in jeden Kontext. In vier Situationen ist der Aufwand meist höher als der Nutzen.

• Throwaway-PoCs und Wegwerf-Prototypen. Wenn absehbar ist, dass die API in wenigen Wochen wieder verschwindet, erzeugt die Design-Phase vor allem Reibung. Code-First reicht hier meist aus.
• Single-Team-interne APIs ohne externe Konsumenten. Eine API, die nur ein Team für das eigene Backend nutzt, profitiert kaum von einer eigenen Konsumenten-Review-Phase. Der Koordinationsvorteil bleibt in diesem Fall gering.
• GraphQL-First-Stacks. In GraphQL-Setups lebt das Schema meist im Code und wird über Introspection veröffentlicht. Eine zusätzliche OpenAPI-Spec wäre redundant. Hier gilt Schema-First, nicht Spec-First.
• Sehr kleine Teams ohne dediziertes API-Design. In Ein- oder Zwei-Personen-Setups übernimmt der Backend-Entwickler häufig beide Rollen. Die Trennung zwischen Design und Implementierung verschwimmt, und der Spec-First-Vorteil reduziert sich meist auf Code-Generation statt auf bessere Koordination.

Spec-First in der CI/CD-Pipeline

Spec-First gehört genauso in die CI/CD-Pipeline wie der Code, den die Spec beschreibt. In einem produktionserprobten Setup hängen vier Integrationspunkte zusammen, beginnend beim Repository und endend an der Build-Stufe. Die OpenAPI-Datei liegt im selben Repository wie der Backend-Code, häufig unter docs/openapi.yaml oder api/spec.yaml, und Pull Requests mit Spec-Änderungen durchlaufen denselben Review-Prozess wie Code-Änderungen. Vor jedem Merge prüft ein OpenAPI Linter die Spec gegen den Style Guide. Naming-Konventionen, Auth-Pflichten, Schema-Konsistenz und weitere Regeln werden automatisch validiert.

Parallel zum Linter wird aus der Spec ein Mock-Server erzeugt, der lokal oder in einer Staging-Umgebung läuft, sodass Konsumenten ihre Integration anhand des Mocks testen können, lange bevor das Backend fertig ist. Tools wie Prism oder die Mock-Funktion in api-portal.io übernehmen diesen Schritt. Nach jedem Backend-Build prüfen schließlich Contract Tests, ob das tatsächliche Backend-Verhalten zur Spec passt. Erkennt der Test eine Abweichung, scheitert der Build, und die Spec bleibt dauerhaft verlässlich.

Wie api-portal.io Spec-First unterstützt

In api-portal.io werden OpenAPI-Specs zentral verwaltet, inklusive Versionierung und Diff-Funktion zwischen Versionen. Mock-Server lassen sich direkt aus jeder Spec erzeugen, ohne zusätzliches Tool. Der eingebaute Linter prüft Specs im PR gegen Style-, Security- und Compliance-Regeln. Code-Generation für Server-Stubs und Client-SDKs ist für die meisten gängigen Sprachen verfügbar.

Die Developer Tools unterstützen die Einbindung in Entwicklungs- und CI/CD-Workflows.

Häufige Fragen zu Spec-First