API Contract Design Checklist: What to Verify Before You Ship

Once clients depend on an API, changing field names, status codes, or error shapes may require a migration. Review these choices before the first integration goes live.

The checklist covers naming, request semantics, error handling, versioning, and compatibility.

API Contract Design Checklist

Use this as a review checklist. Naming, pagination, and versioning conventions are design choices; document exceptions. HTTP method and status-code behavior should follow HTTP semantics.

Resource and Endpoint Naming

• Use a consistent resource-naming convention, such as plural nouns (/users, /orders, /invoices)
• Prefer resource-oriented paths; document action endpoints when an operation does not fit a resource update
• Nested resources reflect genuine ownership, not just relation (/users/42/addresses is fine; /users/42/global-settings should probably be its own root resource)
• No trailing slashes (or consistent trailing slashes if your framework requires them)
• All URL segments are lowercase and use hyphens, not underscores or camelCase
• Field names in request and response bodies follow a single consistent convention — snake_case or camelCase, documented and applied uniformly

HTTP Methods and Semantics

• GET does not request a state change; incidental effects such as access logging are acceptable
• Repeating an identical PUT or DELETE has the same intended effect as making it once; response status may differ
• POST processes a request according to the endpoint contract and is not limited to creation; PUT creates or replaces a resource at a known URI
• PATCH is used for partial updates where appropriate, with clear documentation of which fields are patchable
• For operations where idempotency is critical (payments, order submission), an Idempotency-Key header is accepted and honored

HTTP Status Codes

• Success codes match the result; for resource creation, use 201 and identify the primary resource with Location when appropriate
• Client errors return 4xx, not 200 with an error body
• Validation failures return 400 or 422, not 500
• Use 401 with the required authentication challenge when credentials are missing or invalid; use 403 for refused access, or 404 when deliberately concealing a resource
• Rate limit responses use 429; include Retry-After when the server can provide useful retry timing
• All error responses have the same shape — consistent code, message, and optional field keys

Error Response Shape

• Every error response includes a machine-readable code string, not just a human-readable message
• Validation errors identify which field or parameter caused the failure
• Error codes are documented alongside their HTTP status mappings
• Error messages are actionable — they tell the caller what to do, not just what went wrong

Versioning

• The API includes a version in the URL path (/v1/) or a documented version header
• The version is present from the first public release, even if it is the only version today
• A deprecation policy is documented: how much notice consumers will receive before a breaking change

Request and Response Contracts

• All response fields are documented with their type, nullability, and allowed values
• Optional fields in requests are explicitly labeled as optional with documented defaults
• Document the meaning of absent and null fields, including any difference between them
• Document timestamp format, precision, and time zone; distinguish instants from local calendar dates and recurring local times
• Monetary values are integers (cents/pence) or strings with explicit decimal precision — never floats
• Boolean fields do not use numeric proxies (0/1) in JSON responses

Pagination

• Bound collection responses with pagination or a documented maximum result size
• Default page size and maximum page size are documented
• Document pagination metadata and whether clients find it in the response body, Link headers, or both
• Behavior at the last page is defined — has_more: false or an absent next_cursor

Authentication and Security Headers

• Authentication and resource-concealment behavior is consistent with the documented access policy
• The authentication scheme is documented — Bearer token, API key header, OAuth scopes
• Rate limiting is applied and the limits are documented
• Validate request media types against the endpoint contract, including JSON, uploads, or form data as applicable
• CORS policy is intentional, not left at the framework default

OpenAPI Specification

• Every endpoint has a summary and description in the spec
• Every request parameter and response field has a description
• Request and response examples are included for the happy path and at least one error case
• The spec is generated from or validated against the actual implementation — they should not drift

Backward Compatibility Verification

• Review each change against existing clients; optional response fields and new endpoints can be compatible, while stricter validation or new required inputs may break consumers
• No existing field has been renamed, removed, or had its type changed without cutting a new version
• Removing an endpoint is preceded by a deprecation period with a Deprecation and Sunset header on that endpoint

How to Use This List

Use this list during design review and again before opening the API to its first consumer.

For an existing API, identify which corrections affect clients. Use a migration or new version for breaking changes; a naming preference alone does not justify disrupting consumers.

Discuss an API contract review with LinkIT.