Bevor du über Endpoints, Payloads oder Auth nachdenkst, brauchst du Klarheit über drei Fragen: Für wen ist die API? Was soll sie können? Und was explizit nicht? Ohne diese Grundlage triffst du Designentscheidungen im Nebel – und wunderst dich später, warum die Hälfte der Features niemand braucht und die andere Hälfte nicht skaliert.
Dieser Artikel hilft dir, den Rahmen für deine API zu definieren, bevor du ins Detail gehst. Am Ende hast du einen One-Pager, der Zielgruppe, Use Cases und Non-Goals dokumentiert – ein Artefakt, das du in jedem Design-Review als Referenz nutzen kannst.
Zielbild
Nach diesem Artikel kannst du:
- Die primären Nutzergruppen deiner API benennen und priorisieren
- Kritische Use Cases identifizieren und von Nice-to-haves abgrenzen
- Non-Goals explizit formulieren, um Scope Creep zu verhindern
- Domänengrenzen ziehen: Was gehört zur API, was ist externe Abhängigkeit?
- Erste SLO-Anforderungen und Compliance-Constraints ableiten
Kernfragen
Bevor du weiterliest, versuche diese Fragen für dein Projekt zu beantworten:
- Wer sind die Nutzer? Interne Teams, Partner, öffentliche Entwickler?
- Welche Use Cases sind kritisch? Was muss am ersten Tag funktionieren?
- Was sind explizite Non-Goals? Was bauen wir bewusst nicht?
- Welche Domänen besitzen wir? Wo sind wir Source of Truth, wo integrieren wir nur?
- Welche Constraints gibt es? Datenschutz, Compliance, SLOs?
Wenn du bei mehr als zwei Fragen unsicher bist, ist dieser Artikel genau richtig.
Nutzergruppen verstehen
APIs haben unterschiedliche Konsumenten mit unterschiedlichen Bedürfnissen. Ein internes Frontend-Team hat andere Anforderungen als ein Partner mit eigenem Backend oder ein öffentlicher Entwickler, der deine API zum ersten Mal sieht.
Typische Nutzergruppen
| Gruppe | Charakteristik | Implikation |
|---|---|---|
| Internes Frontend | Kennt Domäne, kurze Feedbackzyklen | Reagiert schnell, braucht klare Deprecation-Phasen |
| Internes Backend | Service-zu-Service, hohe Last | Braucht stabile Contracts, klare Fehlercodes |
| Partner | Eigene Systeme, längere Integrationszyklen | Braucht Stabilität, Dokumentation, Support |
| Öffentlich | Unbekannte Entwickler, heterogene Clients | Braucht Self-Service, Sandbox, strikte Versionierung |
Regel: Definiere eine primäre Zielgruppe. Wenn du versuchst, alle gleich gut zu bedienen, bedienst du niemanden gut. Sekundäre Gruppen kannst du später adressieren.
Anti-Pattern: Die API ist für alle. – Das führt zu einem Design, das für niemanden optimiert ist.
Use Cases priorisieren
Nicht jeder Use Case ist gleich wichtig. Identifiziere die Use Cases, die für den Erfolg deiner API entscheidend sind, und designe zuerst für diese.
Kritische vs. Nice-to-have Use Cases
Ein Use Case ist kritisch, wenn er:
- Den Hauptnutzen der API repräsentiert
- Ohne ihn die API keinen Sinn ergibt
- Hohe Last oder strenge Latenzanforderungen hat
- Bei Fehlern geschäftskritische Konsequenzen verursacht
Beispiel: Bei einer Payment-API ist Zahlung autorisieren kritisch. Zahlungshistorie exportieren ist Nice-to-have.
Use Case Mapping für APIs
Dokumentiere für jeden kritischen Use Case:
- Trigger: Was löst den Use Case aus?
- Schritte: Welche API-Calls sind nötig?
- Erfolgskriterium: Wann ist der Use Case erfolgreich?
- Fehlerszenarien: Was kann schiefgehen, wie reagiert die API?
Anti-Pattern: Alle Features gleichzeitig designen. Das führt zu inkonsistenten Entscheidungen, weil du den Fokus verlierst.
Non-Goals explizit machen
Non-Goals sind keine Absage, sondern eine Priorisierung. Sie verhindern Scope Creep und geben dem Team Klarheit, was nicht in den aktuellen Scope gehört.
Gute Non-Goals
- Kein öffentlicher Zugang in v1 – nur authentifizierte Partner.
- Keine Echtzeit-Updates – Polling ist für unsere Use Cases ausreichend.
- Keine Bulk-Operationen – Clients iterieren über Einzelressourcen.
- Keine GraphQL-Variante – wir standardisieren auf REST.
Schlechte Non-Goals
- Keine Performance-Optimierung. – Das ist kein Non-Goal, das ist ein Problem.
- Keine Dokumentation. – Siehe oben.
Regel: Ein Non-Goal ist nur dann sinnvoll, wenn jemand es plausibel als Goal vorschlagen könnte.
Domänengrenzen ziehen
Deine API ist selten eine Insel. Sie interagiert mit anderen Systemen, nutzt externe Daten oder delegiert Operationen. Kläre früh, wo deine Domäne endet.
Source of Truth vs. Integration
| Frage | Source of Truth | Integration |
|---|---|---|
| Wer definiert das Datenmodell? | Du | Externes System |
| Wer ist für Konsistenz verantwortlich? | Du | Externes System |
| Wie gehst du mit Ausfällen um? | Eigene Logik | Graceful Degradation |
Beispiel: Du baust eine E-Commerce-API. Produktdaten kommen aus einem PIM (Integration), aber Warenkörbe und Bestellungen sind deine Domäne (Source of Truth).
Notiere auch Abhängigkeiten mit eigenen SLAs oder Release-Zyklen. Sie setzen harte Grenzen für deine Stabilitäts- und Verfügbarkeitszusagen.
Anti-Pattern: Daten aus externen Systemen 1:1 durchreichen, ohne eigene Abstraktion. Das koppelt deine API an externe Änderungen.
SLOs und Constraints
Bevor du implementierst, solltest du wissen, welche nicht-funktionalen Anforderungen gelten. SLOs (Service Level Objectives) beschreiben interne Zielwerte, SLAs (Service Level Agreements) sind externe Zusagen. Diese Rahmenbedingungen beeinflussen fundamentale Designentscheidungen.
Typische Constraints
- Latenz: P99 (serverseitig) < 200ms für kritische Endpoints?
- Verfügbarkeit: 99.9% Uptime? Was passiert bei Wartung?
- Datenschutz: Welche Daten sind personenbezogen? Wo dürfen sie gespeichert werden?
- Compliance: PCI-DSS, SOC 2, DSGVO – welche Standards gelten?
- Datenklassifikation & Aufbewahrung: Welche Datenklassen, wie lange?
- Audit-Logging: Welche Aktionen müssen revisionssicher protokolliert werden?
- Datenresidenz: In welchen Regionen dürfen Daten liegen?
- Rate Limits: Wie viele Requests pro Sekunde sind realistisch?
- Security/Abuse: Welche Missbrauchsszenarien gibt es, welche AuthZ-Grenzen?
Klarstellung: „Constraints“ ist der Oberbegriff. SLOs sind ein Teil davon (messbare Zielwerte wie Latenz und Verfügbarkeit), andere Constraints sind z.B. Datenschutz, Compliance oder Datenresidenz.
Regel: SLOs sind keine Wunschliste, sondern Verpflichtungen. SLOs sind interne Zielwerte, SLAs sind externe Zusagen. Definiere nur, was du auch messen und einhalten kannst.
Anti-Pattern: SLOs erst nach dem Launch definieren. Dann ist es zu spät, fundamentale Architekturentscheidungen zu ändern.
Regeln & Anti-Patterns
Do
- Dokumentiere Zielgruppe und Priorität schriftlich
- Definiere maximal 3-5 kritische Use Cases für v1
- Formuliere Non-Goals explizit und begründe sie
- Kläre Domänengrenzen mit abhängigen Teams
- Leite SLOs aus Geschäftsanforderungen ab, nicht aus technischen Wünschen
Don't
- API für alle designen ohne klare Priorisierung
- Alle Features gleichzeitig spezifizieren
- Non-Goals weglassen (ist doch klar, was wir nicht machen)
- Externe Abhängigkeiten ignorieren oder als gegeben hinnehmen
- SLOs raten oder von anderen Projekten kopieren
Artefakt: API-Übersicht (One-Pager)
Nutze dieses Template, um die Ergebnisse dieses Artikels zu dokumentieren. Ein One-Pager reicht – das Ziel ist Klarheit, nicht Vollständigkeit.
# API-Übersicht: [Name]
## Zielgruppe
- **Primär:** [z.B. Partner-Backends für Auftragsintegration]
- **Sekundär:** [z.B. Internes Analytics-Team]
## Ziel & Erfolg
- **Ziel/Nutzen:** [z.B. Auftragsprozess für Partner automatisieren]
- **Erfolgskriterien:** [z.B. 80% der Partner integrieren in 90 Tagen]
## Verantwortlichkeiten
- **Owner:** [z.B. Team Payments]
- **Stakeholder:** [z.B. Sales, Operations]
- **Ansprechpartner:** [z.B. api@firma.de]
## Kritische Use Cases (v1)
1. [Use Case 1: z.B. Auftrag anlegen und Status abfragen]
2. [Use Case 2: z.B. Webhook für Statusänderungen empfangen]
3. [Use Case 3: ...]
## Non-Goals (v1)
- [z.B. Kein öffentlicher Zugang, nur authentifizierte Partner]
- [z.B. Keine Bulk-Imports, Clients iterieren einzeln]
- [z.B. Keine Echtzeit-Updates via WebSocket]
## Domänengrenzen
- **Source of Truth:** [z.B. Aufträge, Statushistorie]
- **Integration:** [z.B. Kundendaten aus CRM, Produkte aus PIM]
## Constraints
- **Latenz:** [z.B. P99 < 500ms für Auftragsanlage]
- **Verfügbarkeit:** [z.B. 99.5% während Geschäftszeiten]
- **Datenschutz:** [z.B. Keine PII in Logs, DSGVO-konform]
- **Compliance:** [z.B. Keine speziellen Anforderungen in v1]
- **Security/Abuse:** [z.B. Threat-Modeling, Abuse-Rate-Limits, AuthZ-Checks]
- **Versionierung:** [z.B. SemVer, Deprecation-Policy 6 Monate]
Checkliste
Bevor du zum nächsten Artikel gehst, prüfe:
- [ ] Primäre Zielgruppe ist definiert und priorisiert
- [ ] Alle kritischen Use Cases sind dokumentiert (typisch 1–5)
- [ ] Non-Goals sind explizit formuliert
- [ ] Domänengrenzen sind mit abhängigen Teams abgestimmt
- [ ] SLOs, Security und Compliance-Constraints sind bekannt
- [ ] Versionierungs- und Deprecation-Policy ist grob definiert
- [ ] API-Übersicht (One-Pager) ist ausgefüllt
Wie es weitergeht
Im nächsten Teil geht es um API-Stil und Grundprinzipien: REST, RPC oder GraphQL? Welche Konsistenzregeln gelten überall? Und wie stellst du sicher, dass dein Team dieselbe Sprache spricht?
Alle Teile der Serie: Serie: API-Design