In Practice — Designing an API Against All 15 Principles

A team is designing a public API for a payment notification service. Users register a webhook URL; the service calls it when payment events occur.

Applying the checklist:

• Abstraction (P1): The webhook contract exposes event type and payload, not internal database schema. Callers never see implementation details.
• Idempotency (P5): Each event carries a unique event_id. Consumers must deduplicate. The service must guarantee each event is delivered at least once, not exactly once.
• Reproducibility (P6): Replaying the event stream from any point must produce the same consumer state. Events are immutable.
• Fault Tolerance (P9): If a consumer webhook is unreachable, the service retries with exponential backoff. It does not lose the event.
• Observability (P10): Every delivery attempt is logged with outcome, latency, and HTTP status. Dashboards show per-consumer delivery rates.
• Fail Fast (P13): Invalid webhook URLs are rejected at registration, not at delivery time.
• Least Privilege (P14): The notification service has read-only access to the payment event stream. It cannot write to payment records.

Run this check on any API during design review and you will find the absent principles before they become incidents.