API-Design für Produkte, die weiter evolvieren

Die Domain modellieren, nicht den Screen

Interfaces ändern sich schneller als die Konzepte dahinter. Eine API, die um einen spezifischen Screen gebaut ist, tendiert dazu, Presentation State zu exponieren und duplicate Endpoints zu erzwingen, wenn neue Clients erscheinen. Starten Sie mit stabilen Domain Resources, ihrem Lifecycle und den Operations, die das Business erkennt.

Das erfordert keine theoretische Reinheit. Eine produktseitige API kann Daten für eine Journey aggregieren, aber die Aggregation sollte klaren Purpose und Ownership haben. Vermeiden Sie, Database Tables direkt zu leaken; Storage Structure ist ein Implementation Detail, das sich irgendwann ändern muss.

Compatibility ist ein Feature

Consumer deployen auf unterschiedlichen Schedules, besonders Mobile Applications und externe Integrations. Additive Changes sind meist sicherer: neue optionale Fields, neue Resources und neue Enum Values mit tolerant Readers. Bestehendes Verhalten zu entfernen oder neu zu definieren braucht einen Migration Plan, Telemetry und ein publiziertes End Date.

Versioning ist nützlich, wenn Semantics wirklich divergieren, aber Version Numbers ersetzen keine Compatibility Discipline. Eine versionierte API kann Consumer trotzdem durch geänderte Ordering, Error Behavior, Limits oder Authorization überraschen. Pflegen Sie ein maschinenlesbares Schema und testen Sie repräsentative Consumers dagegen.

• Behandeln Sie unbekannte Enum Values sicher
• Dokumentieren Sie Nullability und Defaults
• Nutzen Sie Contract Tests für kritische Consumers
• Messen Sie Deprecated-Field Usage vor dem Removal

Mutations brauchen Identity

Retries sind über unzuverlässige Networks unvermeidlich. Für wichtige Mutations akzeptieren Sie einen Idempotency Key, scoped auf Caller und Operation. Speichern Sie das Result, sodass ein wiederholter Request das originale Outcome zurückgibt statt die Action erneut auszuführen.

Long-running Work sollte eine Operation Resource mit expliziten States zurückgeben. Clients können polln oder subscriben, ohne einen fragilen Request offen zu halten. Das verbessert auch Support: Das System kann erklären, ob Work queued, active, completed oder failed ist — und warum.

Authorization gehört in den Contract

Authentication etabliert Identity; Authorization entscheidet, ob diese Identity eine Operation auf einer Resource ausführen darf. Erzwingen Sie das auf dem Server an der engsten bedeutsamen Boundary. Einen Button im Client zu verstecken ist Interface Behavior, nicht Access Control.

Multi-Tenant Systems brauchen Tenant Context, der nicht frei vom Client geliefert und trusted werden kann. Leiten Sie Scope aus verifizierter Membership ab, validieren Sie Ownership bei jedem Resource Access und loggen Sie administrative Actions mit genug Context für Audit und Investigation.

Für Consumer Understanding optimieren

Konsistentes Naming, vorhersagbare Pagination, nützliche Errors, Examples und ein klares Change Log reduzieren Integration Time mehr als clevere Protocol Choices. Eine API ist erfolgreich, wenn Consumers sie korrekt nutzen können, ohne ihre interne History zu lernen.

Design Reviews sollten Client Engineers und Operational Scenarios einschließen. Das Interface wird länger leben als die erste Implementation, also investieren Sie Precision in die Teile, die am härtesten zu ändern sind: Identifiers, Semantics, Authorization und Lifecycle.