API contract testing

API Testing

Test the contract callers rely on: requests, responses, errors and side effects, not the server's internals.

Contract

• The source of truth is the API's spec or schema (OpenAPI, JSON Schema, GraphQL schema, or the typed contract in code). Validate responses against it with a schema validator, not field by field.
• For each changed endpoint check every documented status, the content type and required headers, field types, required and nullable fields, enum values and formats (dates, emails, ids).
• Backward compatibility: compare with the previous contract. Removed fields, changed types, removed enum values, new required request fields and changed defaults all break callers.

Cases per endpoint

• Happy path per method: create returns 201 with the resource, read returns it, update changes only what was sent, delete returns 204 and a later read returns 404.
• Validation: missing, empty, wrong type, too long, out of range, unicode and special characters; expect 400 or 422 with the documented error shape naming the field.
• Unknown ids give 404; a duplicate unique value gives 409.
• Access: no token gives 401; another user's or tenant's record gives 403 or 404, and nothing changes.
• Lists: page size limits and totals, a stable order, filters, an empty list, the last page and the one after it.
• Repeats: PUT and DELETE sent twice give the same result. A POST retried with the same idempotency key creates one resource and replays the first response; the same key with a different body is rejected.
• Errors leak nothing: no stack traces, SQL, internal paths or other users' data.
• Rate limits answer 429 with a Retry-After header.
• Check side effects through the API or other visible results, not only the response body.

Incoming webhooks

• A valid signature is accepted; a missing or wrong signature, or a stale timestamp, is rejected and nothing is processed.
• The same event delivered twice is processed once and acknowledged both times.
• Late and out-of-order events are handled (an update before its create, an old event after a newer one).
• The endpoint answers within the provider's timeout, slow work runs in the background, and the provider's retry after a failure succeeds without duplicates.

Outgoing calls and webhooks

• Outgoing payloads match their documented schema and are signed; failed deliveries retry with backoff and a limit, then become visible.
• External services are tested against their sandbox or a mock at the network boundary: success, each documented error, timeouts, 429 and 5xx, malformed responses. Tests never call a real payment, email or messaging service.
• Every call has a timeout, and an unknown outcome (a timeout after sending) does not lead to a duplicate.

Test hygiene

• Run against a local or test environment, never production. Each test creates and removes its own data with unique values; no shared state or fixed ids between tests.
• Log the full request and response of a failing test, with secrets redacted.

Before you finish

• Changed endpoints validated against the contract, error responses included.
• Validation, not found, conflict, access and repeat cases covered.
• Webhooks: signatures, duplicates, ordering and retries tested.
• External services only through sandboxes or mocks; backward compatibility checked.