Connect systems and services

API Design and Integration

Contract first

• Define the interface before the implementation: inputs, outputs, errors, permissions. Every observable behavior will be depended on, so expose things on purpose and do not leak internals.
• Change by addition: new fields optional, nothing removed or retyped. Breaking changes need a migration path for every consumer, not a second version kept forever.
• One error shape everywhere (a machine-readable code, a human message, optional details) and consistent statuses: 400 bad input, 401 not signed in, 403 not allowed, 404 not found, 409 conflict, 422 failed validation, 500 internal (never with internal details).
• Validate at the boundary: requests, form submissions, environment variables and every third-party response, which is untrusted. Internal code then trusts the parsed types.
• Predictable naming: plural nouns without verbs in paths (GET /tasks, PATCH /tasks/{id}), one case style for fields, is/has prefixes for booleans. PATCH for partial updates.
• Every list endpoint paginates with a limit and a stable order.

Idempotency keys

• Derive the key from the intent, not the attempt: the client sends one key and reuses it on retry, or derive it from an immutable id (charge:v1:{orderId}). Never a fresh UUID or a timestamp per attempt.
• Claim it atomically: insert the key with state in_progress and a hash of the request under a unique constraint; on a conflict, replay the stored response or reject. A read followed by an insert is a race.
• The same key with a different payload fails loudly (422).
• A duplicate arriving while the first is still running gets a deliberate answer: 409, a bounded wait, or 202 with a status URL. Never let it through.
• Every call has three outcomes: success, failure and unknown. Record the intent before calling out.
• Keep keys longer than the longest redelivery path, including dead-letter replays.

Calling other services

• Every call has a timeout. Pass the remaining deadline down the chain; a retry never gets a fresh full timeout.
• Retry only 5xx, 408, 429 and network errors; never 400, 401, 403, 404, 409 or 422.
• Retry at one layer only. Check the HTTP client's or SDK's built-in retries; three layers of 3 retries are 27 calls.
• Backoff with full jitter: delay = random(0, base × 2^attempt), base around 200 ms, about 3 retries, and a cap. Honor Retry-After.
• Keep retries under about 10% of traffic (a retry budget) so they never multiply load on a struggling service.
• A circuit breaker opens after about 5 consecutive failures, fails fast for about 30 s, then lets one probe through.
• Under overload, shed load with a fast 503 instead of queueing slowly.
• Every retried operation must be idempotent; pass the provider's idempotency key.

Webhooks

• Verify the signature on the raw body first, then parse and validate.
• Record the event id under a unique constraint in the same transaction as the work; a duplicate returns 2xx without redoing it.
• Answer fast; do slow work in a background job. Expect events late, twice and out of order.

Before you finish

• Typed inputs and outputs, one error format, validation at the boundary.
• Changes are additive; lists paginate.
• Unsafe operations honor an atomically claimed idempotency key.
• Outgoing calls have deadlines, limited jittered retries and a breaker.
• Webhooks are verified and deduplicated.