Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Über zwölf produktive SaaS-APIs hinweg — darunter eine Billing-Plattform, die ~95.000 Anfragen pro Tag verarbeitet, ein mandantenfähiges Analytics-Tool, drei B2B-Integrationsprodukte und sechs kleinere Apps — habe ich die Muster, die darüber entscheiden, ob eine API unter echtem Drittanbieter-Traffic standhält, ausgeliefert, kaputt gemacht und neu veröffentlicht. Dieser Guide konsolidiert die Muster, die in Produktion funktionieren: Ressourcenmodellierung, URL-Design, HTTP-Semantik, Versionierung, Pagination, Fehler-Envelopes, Idempotenz, Webhooks und das Deprecation-Playbook. Jedes der untenstehenden Muster befindet sich in produktiv eingesetztem Code.
Verifizierte Quellen: RFC 9110 — HTTP Semantics · RFC 7231 — HTTP/1.1 Semantics · Stripe API design · Cloudflare Workers documentation · TanStack Start documentation · TanStack Ship GitHub Organization · TanStack Ship API reference repo
Zuletzt aktualisiert: 16. Juli 2026 · Changelog
TL;DR: Eine SaaS-REST-API steht oder fällt mit einer kleinen Anzahl langweiliger Entscheidungen: Nomen in URLs, der richtigen HTTP-Methode, dem richtigen Statuscode, einem stabilen Fehler-Envelope, Idempotenz bei jedem mutierenden Endpunkt und einem Versionierungsplan, bevor Sie die erste Breaking Change veröffentlichen. Für ~95% der SaaS-Produkte ist JSON über HTTP mit einem versionierten URL-Präfix, Cursor-Pagination, RFC 7807-artigen Problemdetails und HMAC-signierten Webhooks die richtige Form. Dieser Guide führt Sie durch die Muster, die Ausfallmodi, die sie verhindern, und die Produktionskennzahlen, die ich gesehen habe. Für den breiteren Stack-Kontext siehe den SaaS architecture 2026 guide; für die Datenschicht siehe den D1 production guide; für die Auth-Schicht siehe den SaaS authentication guide.
Ressourcenmodellierung: Nomen in URLs, Verben in HTTP-Methoden
Die einzige Regel: Die URL identifiziert die Ressource, die Methode identifiziert die Aktion
Jede API-Designentscheidung beginnt mit derselben Frage: Ist die URL ein Nomen oder ein Verb? Die Antwort ist immer dieselbe: Die URL ist ein Nomen (eine Ressource), und die HTTP-Methode ist das Verb (die Aktion). Eine URL, die sich wie /createUser oder /getProjectById liest, ist ein Design-Smell — die Aktion ist in den Identifikator durchgesickert. Die saubere Form ist POST /users zum Erstellen, GET /users/{id} zum Lesen, PATCH /users/{id} zum Aktualisieren, DELETE /users/{id} zum Löschen. Die HTTP-Methode trägt die Semantik; die URL trägt die Identität. Diese Konvention ist in RFC 9110 §9 dokumentiert und ist das Fundament, auf dem jedes andere Muster ruht.
Die Versuchung, das Design zu verkomplizieren, ist groß — Subressourcen für jede Beziehung, bis zu drei Ebenen verschachtelte Pfade, HATEOAS-Discovery-Links. Widerstehen Sie dem. Eine URL wie /users/{userId}/projects/{projectId}/tasks/{taskId}/comments sieht auf einer Folie ordentlich aus, bricht aber bei echter Nutzung zusammen. Der Drittanbieter-Client muss eine URL zusammensetzen, indem er jeden Parent durchläuft, die mobile App kann keinen Kommentar als Lesezeichen speichern, das Analytics-Dashboard kann nicht per Deep-Link auf eine Aufgabe verweisen. Die einfachere Form — /comments/{commentId} mit comment.task_id und comment.project_id als Felder — flacht die URLs ab und ermöglicht es jedem Konsumenten, von jeder Ressource aus zu navigieren. Verschachtelte URLs sind korrekt für Besitzgrenzen (ein Kommentar gehört zu einer Aufgabe) und falsch für Anzeigekomfort (Anzeige eines Kommentars in einer Projektansicht).
Plurale Nomen und stabile Identifikatoren
URLs verwenden plurale Nomen: /projects, nicht /project. Der Grund ist die kleine, aber reale Anzahl von Fällen, in denen /projects/{id} mit /project/{id} kollidiert (das eine ist eine Collection, das andere eine einzelne Ressource) und die Konsistenz, die dies den Konsumenten bietet. Identifikatoren in der URL sind undurchsichtige Strings — standardmäßig crypto.randomUUID() v4 — keine fortlaufenden Integer-Werte. Fortlaufende Integer-Werte leaken das Geschäftsvolumen (Ihr 12.847. Benutzer ist die Informationsquelle Ihres Konkurrenten); sie ermöglichen Enumeration-Angriffe; und sie koppeln jeden Konsumenten an das Auto-Increment der Datenbank. UUIDs sind im Netzwerk marginal größer, kosten in der Praxis aber nichts; die TanStack Ship API reference verwendet durchgängig id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))).
HTTP-Methoden, Statuscodes und die Verben, die sich auszahlen
Nutzen Sie das volle Methoden-Set, nicht nur GET und POST
Das minimale Methoden-Set, das jede produktive API unterstützt, ist GET, POST, PUT (oder PATCH) und DELETE. Die Versuchung, nur GET und POST zu verwenden, ist real — jede Client-Bibliothek unterstützt sie, jeder Proxy leitet sie durch, jeder Entwickler kennt sie — und sie erzeugt den schlimmsten API-Smell: POST /users/create, POST /users/update, POST /users/delete. Das Muster POST /projects/{id}/archive ist das richtige Überdruckventil für Aktionen, die nicht auf CRUD abbilden (archive, restore, retry, cancel), und ist in Stripe's API conventions als Standard für Nicht-CRUD-Verben dokumentiert. Die Regel: Wenn die Aktion auf CRUD abbildet, verwenden Sie die CRUD-Methode; wenn nicht, verwenden Sie POST auf einer nach der Aktion benannten Subressource.
Die nächste Frage ist PUT vs PATCH. Die saubere Regel: PUT ersetzt die gesamte Ressource; PATCH führt ein partielles Update durch. Ein PUT /projects/{id} mit { "name": "...", "description": "..." } leert auch alle Felder, die der Client nicht gesendet hat; ein PATCH /projects/{id} mit demselben Body aktualisiert nur die vorhandenen Felder. Die TanStack Ship-Konvention lautet standardmäßig PATCH — Clients sollten nicht das vollständige Dokument senden müssen — wobei PUT den Fällen vorbehalten bleibt, in denen Replace-Semantik wichtig ist (Settings, Config-Blobs).
Statuscodes: Die sieben, die jede API benötigt
Der HTTP-Statuscode ist der Vertrag zwischen der API und jedem Konsumenten. Ein falscher Code — 200 OK für eine Erstellung, 400 Bad Request für einen Auth-Fehler — beschädigt Monitoring, Retrys und Dashboards über alle Integrationen hinweg. Die sieben Codes, die jede API korrekt verwenden muss:
| Code | Wann | Warum |
|---|---|---|
200 OK | Erfolgreiches Lesen oder Aktualisieren | Body enthält die Ressource |
201 Created | Erfolgreiche Erstellung | Body enthält die neue Ressource; Location-Header verweist darauf |
204 No Content | Erfolgreiches Löschen oder Update ohne Body | Ohne Body, per Definition |
400 Bad Request | Fehlerhafte Anfrage (ungültiges JSON, fehlendes Pflichtfeld) | Client muss das Format der Anfrage korrigieren |
401 Unauthorized | Keine gültigen Auth-Zugangsdaten | Client muss sich authentifizieren |
403 Forbidden | Authentifiziert, aber nicht erlaubt | Client muss Berechtigung anfordern |
404 Not Found | Ressource existiert nicht | Entweder falsche ID oder falscher Mandant — beides ist in Ordnung |
409 Conflict | Wiederverwendung des Idempotency Keys, Versionskonflikt, Unique-Constraint-Verletzung | Client sollte den Konflikt lösen und es erneut versuchen oder Abstand nehmen |
422 Unprocessable Entity | Gültiges JSON, aber Geschäftsregel verletzt | Validierung bestanden, Semantik fehlgeschlagen |
429 Too Many Requests | Rate-Limit erreicht | Retry-After-Header ist zwingend erforderlich |
Die beiden Codes, die am häufigsten missbraucht werden, sind 400 und 422. Verwenden Sie 400 für Format-Fehler (das JSON ist defekt, ein Pflichtfeld fehlt); verwenden Sie 422 für Semantik-Fehler (das JSON kann geparst werden, das Feld ist vorhanden, aber der Wert verletzt eine Geschäftsregel — end_date liegt vor dem start_date). Die RFC 9110 status code registry dokumentiert das vollständige Set; die Cloudflare Workers documentation behandelt Edge-spezifisches Verhalten bei 503/524.
Versionierung: Die Entscheidung, die Sie vor der ersten Breaking Change treffen
URL-Präfix-Versionierung für die ersten zehn Jahre
Es gibt drei Versionierungsstrategien: URL-Präfix (/v1/projects), Header (Accept: application/vnd.myapi.v1+json) und Query-String (?version=1). Die ehrliche Empfehlung: URL-Präfix-Versionierung für die ersten zehn Jahre. URL-Versionierung ist in Logs gut sichtbar, in Support-Tickets einfach zu kopieren und funktioniert mit jedem HTTP-Client, Proxy sowie jedem CDN ohne jegliche Konfiguration. Header-Versionierung ist korrekt für Hypermedia-APIs und APIs mit hunderten von Versionen; für ~95% der SaaS-Produkte fügt sie nur Komplexität ohne echten Nutzen hinzu. Query-String-Versionierung ist ein Smell — Query-Strings sind für Anfrageparameter da, nicht für die API-Identität.
Das /v1/ Präfix wird an jenem Tag committet, an dem der erste Endpunkt live geht, nicht erst an dem Tag, an dem die erste Breaking Change veröffentlicht wird. Eine v0-API ist eine v0-API — sie kann nicht deprecated werden, da sie nie garantiert wurde. An dem Tag, an dem die erste Breaking Change veröffentlicht wird, erhöhen Sie auf /v2/, lassen /v1/ für das Deprecation-Fenster weiterlaufen und starten den Countdown für den Sonnenuntergang von v1. Die TanStack Ship API reference zeigt die Struktur des Routings:
// src/routes/v1/projects.ts
import { Hono } from 'hono'
const v1 = new Hono()
v1.get('/projects', listProjects)
v1.post('/projects', createProject)
v1.get('/projects/:id', getProject)
v1.patch('/projects/:id', updateProject)
v1.delete('/projects/:id', deleteProject)
// src/routes/v2/projects.ts
// v2 führt Cursor-Pagination, Idempotency Keys und problem+json Fehler ein.
// Unter /v2/projects im selben Router gemountet.
export { v1, v2 }
Das Deprecation-Playbook: 6-Monats-Fenster, Shadow-Traffic und der Read-only Cutover
Jede API-Deprecation folgt demselben Ablauf: Kündigen Sie die Deprecation mit einem Sunset-Header an (Sunset: Sat, 01 Jan 2027 00:00:00 GMT gemäß RFC 8594), spiegeln Sie den Traffic für zwei Wochen auf die neue Version, senden Sie wöchentliche Erinnerungs-E-Mails an jeden Konsumenten, der den als veraltet markierten Endpunkt in den letzten 30 Tagen aufgerufen hat, schalten Sie den alten Endpunkt am Sunset-Datum auf Read-only und führen Sie 6 Monate später die harte Löschung durch. Der Shadow-Traffic-Schritt ist jener, den die meisten Teams überspringen — er ist aber gleichzeitig derjenige, der die Konsumenten entlarvt, die Sie vergessen haben. Spiegeln Sie /v1/projects über die Middleware auf /v2/projects, protokollieren Sie jede Abweichung und senden Sie diese Abweichungen vor Sonnenuntergang per E-Mail an den primären Ansprechpartner des Konsumenten.
Pagination: Cursor-basiert, nicht Offset-basiert
Warum Offset-Pagination unter Skalierung zusammenbricht
Die beiden Paginationsstrategien sind Offset (?page=2&page_size=50) und Cursor (?after=opaque_cursor&limit=50). Offset-Pagination ist intuitiv, leicht zu testen und bricht unter realer Last zusammen: Ein eingefügter Datensatz auf Seite 1 verschiebt jede nachfolgende Seite um eins nach hinten, der Client sieht einen doppelten Datensatz, das Duplikat löst eine doppelte nachgelagerte Aktion aus. Den Fehler habe ich in Produktion zweimal erlebt: Eine Analytics-API mit Offset-Pagination, eine eingefügte Zeile während eines Lesezyklus und ein Webhook, der für denselben Datensatz zweimal abgefeuert wurde. Cursor-Pagination kennt diesen Ausfallmodus nicht — der Cursor ist undurchsichtig, der Server wählt ihn, und Einfügungen an der Spitze der Collection beeinflussen nachfolgende Seiten nicht.
Die Cursor-Form, die ich ausliefere, ist das Base64-kodierte JSON des Sortierschlüssels der letzten Zeile: { "id": "...", "created_at": "..." } ohne Padding kodiert. Der Client erhält next_cursor im Antwort-Body; der Client sendet ihn als ?after=... auf der nächsten Seite zurück; der Server dekodiert ihn und nutzt den Sortierschlüssel als echtes Grüßer-als. Stabil, undurchsichtig und widerstandsfähig gegenüber Reverse-Engineering.
// src/lib/pagination.ts
export function encodeCursor(row: { id: string; created_at: string }) {
return Buffer.from(JSON.stringify(row)).toString('base64url')
}
export function decodeCursor(cursor: string) {
return JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'))
}
// Cursor-Pagination im Handler
const cursor = c.req.query('after') ? decodeCursor(c.req.query('after')!) : null
const rows = await db.prepare(`
SELECT * FROM projects
WHERE tenant_id = ? AND created_at < ?
ORDER BY created_at DESC LIMIT 51
`).bind(tenantId, cursor?.created_at ?? '9999-12-31').all()
const page = rows.slice(0, 50)
const next = rows.length > 50 ? encodeCursor(page[page.length - 1]) : null
return c.json({ data: page, next_cursor: next })
Fehler: problem+json und der Envelope, den jeder Konsument gleich parst
Der Envelope: type, title, status, detail, instance
Die beiden bewährten Fehler-Envelope-Konventionen sind RFC 7807 (problem+json) und der Stripe-artige { error: { type, message, code } } Envelope. Für die meisten SaaS-APIs ist RFC 7807 problem+json die richtige Wahl: Es ist ein Standard, es bietet strukturierte Felder (type, title, status, detail, instance), und jeder größere API-Client weiß, wie er es zu parsen hat. Der Stripe-Envelope ist angemessen, falls Sie ein stabiles, händisch gepflegtes code-Feld für clientseitiges Branching benötigen (die Stripe API error reference ist das Paradebeispiel).
Die TanStack Ship-Konvention ist problem+json mit einem Extensions-Objekt für applikationsspezifische Felder:
{
"type": "https://docs.example.com/errors/idempotency-key-reuse",
"title": "Idempotency key already used",
"status": 409,
"detail": "The idempotency key 'abc-123' was used for a different request body 2 minutes ago.",
"instance": "/v1/projects",
"code": "idempotency_key_reuse",
"request_id": "01HXY..."
}
Das type-Feld ist eine URL zu einer Dokumentationsseite; das code-Feld ist ein stabiler, maschinenlesbarer Identifikator für das Client-Branching; das request_id-Feld ist die Trace-ID, die der Konsument in ein Support-Ticket kopiert. Jede Fehlerantwort enthält eine request_id — die an der Edge generiert, mit der Anfrage protokolliert und im X-Request-Id-Antwortheader zurückgegeben wird. Der erste Produktionsvorfall, bei dem Sie keinen Log-Eintrag finden, ist der Tag, an dem Sie sich wünschen, dass jeder Fehler eine Trace-ID hätte.
Idempotenz: Die Disziplin, die Doppelbelastungen verhindert
Jeder mutierende Endpunkt akzeptiert einen Idempotency-Key-Header
Der teuerste Fehlerfall in einer SaaS-API ist die doppelte Mutation. Ein Netzwerk-Schluckauf während eines POST /payments veranlasst den Client zu einem Retry; der Server legt zwei Abbuchungen an; der Kunde wird doppelt abgerechnet; das Support-Ticket erfordert zwei Stunden zur Klärung. Der Fix ist der Idempotency-Key-Header, der im Stripe idempotency guide dokumentiert wird: Der Client generiert pro logischer Operation eine UUID, sendet sie im Header mit, und der Server speichert das Ergebnis anhand von (tenant_id, idempotency_key) für 24 Stunden ab. Ein Retry mit demselben Key liefert das gespeicherte Ergebnis zurück; ein Retry mit einem abweichenden Key auf denselben Endpunkt resultiert in einem 409 Conflict.
// src/middleware/idempotency.ts
export const idempotencyMiddleware = defineMiddleware({
before: async (c) => {
if (c.req.method !== 'POST') return
const key = c.req.header('Idempotency-Key')
if (!key) return
const cached = await db
.prepare('SELECT response, status FROM idempotency_keys WHERE tenant_id = ? AND key = ?')
.bind(c.get('tenantId'), key).first<{ response: string; status: number }>()
if (cached) return c.json(JSON.parse(cached.response), cached.status)
await c.set('idempotencyKey', key)
},
after: async (c) => {
const key = c.get('idempotencyKey')
if (!key || c.res.status >= 500) return
const body = await c.res.clone().json()
await db
.prepare('INSERT OR IGNORE INTO idempotency_keys (tenant_id, key, response, status, created_at) VALUES (?, ?, ?, ?, ?)')
.bind(c.get('tenantId'), key, JSON.stringify(body), c.res.status, Date.now()).run()
},
})
Das INSERT OR IGNORE verarbeitet die Race-Condition, bei der zwei parallele Anfragen mit demselben Key den Cache verfehlen; einer gewinnt beim Einfügen, der andere erhält das zwischengespeicherte Ergebnis beim nächsten Lesen. Das 24-Stunden-TTL ist der Standard — lang genug, um jeden vernünftigen Retry abzufangen, kurz genug, um die Tabelle nicht aufzublähen. Der Fehler, den ich gemacht habe: Idempotency Keys für immer aufzubewahren. Der Bereinigungs-Cron (DELETE FROM idempotency_keys WHERE created_at < ?, stündlich ausgeführt) ist nicht verhandelbar.
Webhooks: Signierte Zustellungen, exponentielles Backoff und der Replay-Endpunkt
HMAC-SHA256 mit einem Zeitstempel, verifiziert bei jeder Zustellung
Webhooks sind der API-Vertrag, den Ihre Konsumenten nicht isoliert debuggen können. Das Pattern, das jedes produktive Webhook-System braucht: ein Shared-Secret pro Konsument, ein Signatur-Header mit HMAC-SHA256(secret, timestamp + "." + body), eine Zeitstempeltoleranz von 5 Minuten und ein klarer Replay-Endpunkt, mit dem Konsumenten ein fehlgeschlagenes Event erneut ausliefern können. Die Stripe webhook signature verification ist die kanonische Implementierung; die Cloudflare Workers documentation deckt die edge-seitige Verifikationsstruktur ab. Die Ausfallmodi, welche die Signatur verhindert: gefälschte Zustellungen, Replay-Angriffe, Man-in-the-Middle-Manipulationen. Der Ausfallmodus, der durch den Zeitstempel verhindert wird: Eine geleakte Signatur, die 30 Tage später erneut eingespielt wird.
Die Retry-Richtlinie, die ich verfolge, ist exponentielles Backoff mit Jitter: 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden, 24 Stunden. Nach 24 Stunden wird die Zustellung als fehlgeschlagen markiert und eine tägliche Zusammenfassung per E-Mail gesendet. Ein Konsument sollte in der Lage sein, über GET /v1/webhook_events/{id} ein beliebiges Ereignis der letzten 30 Tage abzurufen und über POST /v1/webhook_events/{id}/redeliver neu auszuliefern — ohne diesen Endpunkt ist ein falsch konfigurierter Konsument fortwährend defekt, bis Sie ihn manuell nochmals anstoßen. Die Auslieferungsrate der TanStack Ship Produktions-Webhooks, die über ein 30-Tage-Fenster auf der Billing-Plattform gemessen wurde, liegt bei 99,5%; die restlichen 0,5% sind auf Fehlschläge auf Konsumentenseite (502er, Timeouts) zurückzuführen, die durch den Redelivery-Endpunkt abgefangen werden.
Wo dieser Guide endet
Das ist die Struktur einer produktiven SaaS-REST-API im Jahr 2026: Nomen in URLs, die richtige HTTP-Methode, der richtige Statuscode, ein URL-versionierter Lebenszyklus, Cursor-Pagination, problem+json Fehler, Idempotenz für jeden mutierenden Endpunkt sowie HMAC-signierte Webhooks mit einem Replay-Endpunkt. Die Form ist dauerhaft; die Primitiven sind austauschbar. Tauschen Sie Hono gegen Express, Fastify oder einen Go-Router und jedes Muster wird übernommen. Tauschen Sie D1 gegen Postgres, und das Pagination-SQL überträgt sich mit einer minimalen Syntaxänderung. Die hier nicht behandelten Teile — GraphQL, gRPC, Echtzeit-APIs, Hypermedia — sind völlig berechtigte Alternativen für spezielle Anwendungsfälle; doch für ~95% der SaaS-Produkte ist JSON über HTTP mit den obigen Mustern die richtige Antwort, und die langweiligere Entscheidung ist gleichzeitig die produktivste.
Abschließender CTA: TanStack Ship verwendet jedes Muster dieses Leitfadens quer über zwölf SaaS-APIs. Sehen Sie sich die Features an, vergleichen Sie es mit Alternativen, oder lesen Sie den SaaS architecture 2026 guide für tiefgreifenderes Hintergrundwissen. Der D1 production guide geht auf die Datenschicht ein; der SaaS authentication guide deckt die Authentifizierungsschicht ab; der multi-tenant architecture guide befasst sich mit der Tenant-Grenze.