APIs sind selten nur ein paar Endpoints. Sie sind ein Vertrag zwischen Teams, Systemen und Zeitpunkten: Heute muss es funktionieren, nächstes Quartal soll es erweiterbar sein, und in einem Jahr soll es noch debuggbar sein. Wenn das Design wackelt, holen dich die Kosten später ein: Breaking Changes, inkonsistente Fehlerbilder, verwässerte Auth-Regeln oder hektische Sicherheits-Nacharbeit kurz vor dem Go-Live.
Mit dieser Serie möchte ich API-Design als ernsthaften Teil der Produktentwicklung behandeln. Es geht nicht darum, perfekte Spezifikationen zu schreiben, sondern um belastbare Entscheidungen, die Wachstum, Sicherheit und Wartbarkeit ermöglichen.
API-Design passiert vor dem ersten Commit. Was in der Designphase unklar bleibt, wird später teuer: falsche Ressourcenschnitte führen zu Workarounds, fehlende Fehlerkonventionen zu inkonsistenten Clients, und nachträglich eingezogene Sicherheitsregeln brechen bestehende Integrationen. Wer früh entscheidet, hat später weniger zu reparieren.
Die Serie richtet sich an Tech Leads und Backend-Teams genauso wie an PMs und Architektur. Wer implementiert, bekommt konkrete Leitplanken, Anti-Patterns und Beispiele. Wer entscheidet, bekommt einen Rahmen für Trade-offs, Risiken und Go-Live-Kriterien.
Was du hier findest, sind Design-Prinzipien, klare Regeln und kleine Artefakte, die du direkt in Reviews oder Workshops einsetzen kannst. Was du nicht findest, sind vollständige Implementierungen oder interne Details. Die Struktur basiert auf einer Checkliste, die ich in einem realen Projekt (Releasy) genutzt habe, aber die Inhalte sind bewusst generisch gehalten.
Die Serie folgt einer Checkliste, die sich als Review- und Workshop-Tool nutzen lässt. Jeder Teil liefert konkrete Fragen, die du in Design-Reviews stellen kannst, und ein kleines Artefakt – eine Vorlage, Matrix oder Policy – das du direkt übernehmen oder anpassen kannst.
Was die Serie abdeckt
- Einstieg & Serienkarte – dieser Artikel
- Ziele, Scope & Kontext – Nutzer, Use Cases, Non-Goals, SLOs
- API-Stil & Grundprinzipien – REST, RPC, GraphQL, Konsistenzregeln
- Ressourcenmodellierung – Substantive, IDs, Hierarchien
- HTTP-Semantik & Statuscodes – Methoden, 4xx/5xx, Async
- Request/Response-Design – JSON-Schemata, null vs. fehlendes Feld
- Pagination, Filtering, Sorting – Cursor vs. Offset, sichere Filter
- Fehlerbehandlung & Validierung – Fehlerformat, Feldfehler, Trace-IDs
- Authentifizierung (AuthN) – OAuth2, API Keys, Token-Lifetimes
- Autorisierung (AuthZ) – RBAC, ABAC, BOLA-Schutz
- Transport & Kryptografie – TLS, Zertifikate, mTLS
- OWASP API Security – Top-10-Risiken, Mass Assignment, SSRF
- Rate Limiting & Quotas – Dimensionen, Header, Burst
- Resilience & Idempotency – Retries, Circuit Breaker, Idempotenz-Keys
- Caching – ETags, Cache-Control, Conditional Requests
- Observability – Logs, Metrics, Traces, Audit
- Versionierung & Deprecation – URL vs. Header, Sunset-Policy
- Dokumentation & DX – OpenAPI, Beispiele, SDKs
- Testing & Quality Gates – Contract Tests, Schema-Validierung
- Betrieb & Deployment – Rollbacks, Runbooks, Feature Flags
- Datenschutz & Datenlebenszyklus – DSGVO, Retention, Löschung
- Go-Live-Readiness – Freigabekriterien, Risiko-Register
Am Ende der Serie hast du einen Werkzeugkasten: API-Übersicht, Stil-ADR, Ressourcenkatalog, Error-Katalog, Policy-Dokumente und eine Go-Live-Checkliste. Jedes Artefakt ist so gebaut, dass du es in dein Projekt kopieren und anpassen kannst.
Wie es weitergeht
Im nächsten Teil geht es um Ziele, Scope und Kontext: Wer nutzt die API, welche Use Cases sind kritisch, und welche Non-Goals sparen dir später Ärger. Wenn du nichts verpassen willst, findest du den RSS-Feed im Footer.
Alle Teile der Serie: Serie: API-Design