Code-First vs. API-First
Im klassischen Ansatz baut ein Team zuerst die Geschäftslogik, dann das Frontend, und irgendwann – oft unter Zeitdruck – eine API, die das Ganze zusammenhält. Die API wird zum Nebenprodukt der Implementierung.
API-First dreht diesen Prozess um. Bevor eine einzige Zeile Geschäftslogik geschrieben wird, definiert das Team die API-Spezifikation. Endpoints, Request/Response-Formate, Fehlercodes, Authentifizierung – alles wird vorab spezifiziert, dokumentiert und vereinbart.
Erst dann beginnt die parallele Implementierung: Backend und Frontend arbeiten gleichzeitig gegen die definierte Spezifikation.
Warum API-First besser ist
Parallelisierung
Der offensichtlichste Vorteil: Frontend- und Backend-Teams können gleichzeitig arbeiten. Das Frontend mockt die API-Responses basierend auf der Spezifikation. Das Backend implementiert die Endpoints. Beide treffen sich an der definierten Schnittstelle.
In der Praxis reduziert das die Projektdauer um 30-40%. Statt sequenziell zu arbeiten (Backend fertig, dann Frontend), arbeiten beide Streams parallel.
Klare Verträge
Eine API-Spezifikation ist ein Vertrag zwischen Teams. Sie definiert exakt, was gesendet und empfangen wird. Das eliminiert die häufigste Quelle von Integrationsproblemen: Annahmen.
Ohne Spezifikation nimmt das Frontend an, dass ein Feld userName heißt. Das Backend nennt es user_name. Kleiner Unterschied, großer Bug. Mit einer API-Spezifikation ist das unmöglich.
Automatisierte Dokumentation
Aus einer OpenAPI-Spezifikation lassen sich automatisch generieren: API-Dokumentation, Client-SDKs, Server-Stubs, Testfälle und Mock-Server. Das spart nicht nur Zeit, sondern stellt sicher, dass Dokumentation und Implementierung immer synchron sind.
Zukunftssicherheit
Eine gut designte API ist unabhängig vom Frontend. Heute konsumiert eine Web-App die API. Morgen eine Mobile App. Übermorgen ein KI-Agent. Die API bleibt gleich.
Wie man API-First umsetzt
Schritt 1: Stakeholder-Workshop
Bevor die Spezifikation geschrieben wird, identifiziert das Team die Anwendungsfälle. Nicht aus technischer Sicht, sondern aus Nutzersicht: Was muss der Nutzer tun können? Welche Daten braucht er? Welche Aktionen führt er aus?
Dieser Workshop dauert typischerweise zwei bis vier Stunden und involviert Product Owner, Frontend-Entwickler, Backend-Entwickler und – falls vorhanden – Mobile-Entwickler.
Schritt 2: Spezifikation schreiben
Die Spezifikation wird in OpenAPI (ehemals Swagger) geschrieben. Das Format ist maschinenlesbar und gleichzeitig für Menschen verständlich.
Wichtig: Die Spezifikation beschreibt nicht die interne Implementierung. Sie beschreibt die externe Schnittstelle. Welche Daten rein gehen, welche rauskommen, welche Fehler auftreten können.
Schritt 3: Review und Iteration
Die Spezifikation durchläuft ein Review – genau wie Code. Frontend-Entwickler prüfen, ob die API ihre Anforderungen erfüllt. Backend-Entwickler prüfen, ob sie implementierbar ist. Security-Engineers prüfen die Authentifizierung und Autorisierung.
Iterationen in der Spezifikation sind billig. Iterationen in der Implementierung sind teuer. Deshalb investieren wir lieber eine Woche in die Spezifikation als einen Monat in Refactoring.
Schritt 4: Mock-Server aufsetzen
Aus der Spezifikation wird automatisch ein Mock-Server generiert, der realistische Test-Daten zurückgibt. Das Frontend-Team kann sofort mit der Entwicklung beginnen, ohne auf das Backend zu warten.
Schritt 5: Parallele Implementierung
Backend und Frontend arbeiten gleichzeitig. Contract-Tests stellen sicher, dass beide Seiten die Spezifikation einhalten. Sobald das Backend fertig ist, wird der Mock-Server durch den echten Server ersetzt – und alles funktioniert, weil beide gegen denselben Vertrag gebaut wurden.
Häufige Einwände – und Antworten
„Das ist zu viel Overhead für kleine Projekte."
Für ein Wochenend-Projekt? Ja. Für alles, wo mehr als ein Entwickler am Frontend und Backend arbeitet? Nein. Der Overhead zahlt sich innerhalb der ersten Woche zurück.
„Wir wissen am Anfang noch nicht, wie die API aussehen soll."
Dann ist ein Stakeholder-Workshop umso wichtiger. Wenn das Team die API nicht spezifizieren kann, kann es auch nicht sinnvoll implementieren. Die Unklarheit verschwindet nicht durch Code – sie wird nur teurer.
„Die Spezifikation veraltet sofort."
Nur wenn sie manuell gepflegt wird. Mit Contract-Tests, die in der CI-Pipeline laufen, wird jede Abweichung zwischen Spezifikation und Implementierung sofort erkannt.
API-Design-Prinzipien
Ein paar Prinzipien, die sich in unserer Arbeit bewährt haben:
Konsistente Namenskonventionen: camelCase oder snake_case – aber überall gleich. Nichts ist verwirrender als eine API, die zwischen Konventionen wechselt.
Versionierung von Tag eins: Auch wenn heute nur v1 existiert, sollte die API-URL /api/v1/... enthalten. Das macht spätere Breaking Changes handhabbar.
Aussagekräftige Fehlercodes: Nicht nur HTTP-Statuscodes, sondern maschinenlesbare Fehlercodes mit klaren Beschreibungen. { "code": "INVALID_EMAIL", "message": "..." } ist hilfreicher als ein nacktes 400.
Pagination als Standard: Jeder Endpoint, der eine Liste zurückgibt, sollte von Anfang an paginiert sein. Auch wenn die Liste heute nur fünf Einträge hat.
Idempotenz: POST-Requests sollten idempotent sein, wenn möglich. Das macht Retries sicher und vereinfacht die Fehlerbehandlung im Client.
Fazit
API-First Design ist kein Luxus für große Teams. Es ist eine pragmatische Methode, die die häufigsten Probleme in der Softwareentwicklung löst: Kommunikation zwischen Teams, Integrationsprobleme und sequenzielle Abhängigkeiten.
Der Aufwand, eine API-Spezifikation vorab zu schreiben, ist gering im Vergleich zu den Kosten, die durch fehlende Spezifikation entstehen. Wer einmal API-First gearbeitet hat, geht nicht mehr zurück.