A REST API is a contract. The first version is easy to ship; the hard part is changing it without breaking the mobile app, the partner integration and the internal dashboard that depend on it. This checklist covers the decisions that make an API predictable, secure and maintainable.
It is written for a team building or reviewing an API for a business system: an order platform, a payment integration, a CRM, a dashboard or a partner portal. It is not a style preference. Each item is a decision that affects reliability or cost.
Resources and URLs
- Model resources as nouns:
/orders,/customers,/invoices. Use verbs only for actions that are not a resource state change. - Use plural resource names and stable identifiers. Do not expose database auto-increment IDs if they leak volume or are unstable.
- Keep URLs predictable:
/customers/{id}/ordersis easier to understand than a query parameter for every relationship. - Use lowercase, hyphenated path segments. Avoid file extensions and verbs in the path.
- Version the API deliberately. A path prefix such as
/v1is simple and visible; header versioning is also valid but harder to test.
HTTP semantics
- Use
GETfor safe reads,POSTfor creation or actions,PUTfor full replacement,PATCHfor partial updates andDELETEfor removal. - Return the correct status code:
201with aLocationheader for creation,204for a successful empty response,400for invalid input,401for missing authentication,403for missing permission,404for not found,409for conflict,422for semantic validation and429for rate limits. - Do not return
200with an error body. Clients and monitoring tools rely on status codes. - Use
ETagandIf-Matchfor optimistic concurrency where two users can edit the same record. - Honour
Idempotency-Keyfor payment, order and other side-effecting requests. Store the key and the result for a defined window.
Request and response design
- Use JSON with a consistent envelope or a documented bare-resource style. Do not mix both without a reason.
- Use ISO 8601 timestamps with a timezone, and document the timezone of business dates.
- Use strings for money with a currency code, or minor units with a documented currency. Never use floating point for money.
- Define null, missing and empty-string behaviour. They are not the same.
- Return created and updated resources in the response, or document why not.
- Use a consistent error format. RFC 9457 Problem Details is a good default: type, title, status, detail, instance and validation errors.
Pagination, filtering and sorting
- Use cursor pagination for large or changing collections. Offset pagination is acceptable for small, stable lists.
- Return a stable sort order and document it. A list without a defined order can change between requests.
- Whitelist filter and sort fields. Do not pass user input directly into a query.
- Set a maximum page size and a default page size.
- Return pagination metadata: next cursor, has-more flag or total where cheap to compute.
Authentication and authorization
- Use OAuth 2.0 or a signed token with short expiry for partner and user access. Do not invent a custom token scheme.
- Authorize at the object level, not just the route level. A user who can read
/ordersmay not be allowed to read every order. - Scope tokens to the minimum permissions. Separate read and write scopes where possible.
- Rotate secrets, support revocation and log authentication failures.
- Follow the OWASP API Security Top 10, especially broken object-level authorization and excessive data exposure.
Rate limits, caching and reliability
- Publish rate limits and return
429with aRetry-Afterheader. - Use idempotency and retries with backoff for transient failures. Do not retry a non-idempotent request blindly.
- Set timeouts and circuit breakers for downstream services.
- Use caching headers for safe, stable resources. Do not cache authenticated or personalized data without a clear key.
- Return a request ID in every response and include it in logs.
Observability and documentation
- Log method, path, status, latency, request ID and a hashed user identifier. Do not log secrets or full personal data.
- Expose health and readiness endpoints for the platform, not for every business resource.
- Publish an OpenAPI specification and keep it in the repository.
- Document errors, rate limits, pagination, authentication and versioning with examples.
- Provide a sandbox and a changelog. A partner integration should not discover a breaking change in production.
Testing
- Test success, validation failure, authentication failure, permission failure, conflict, rate limit and downstream timeout.
- Test duplicate requests with the same idempotency key.
- Test pagination boundaries and sorting stability.
- Test with the languages and character sets you support, including Bangla text and mixed-language input.
- Run contract tests against the OpenAPI specification in CI.
Versioning and deprecation
A version is a promise. Use a visible version in the path or a documented header. Additive changes such as a new optional field can stay in the same version; removing a field, changing a type or changing an error code is a breaking change. Publish a deprecation policy with a notice period, a sunset date and a migration guide. Return a Deprecation header where appropriate and keep the old behaviour until the sunset date.
Keep a changelog that a partner can read without asking a developer. Include the date, the change, the affected endpoints and the action required. A breaking change announced only in a commit message is not a change management process.
A minimal documentation example
For each endpoint, document the method, path, purpose, authentication, required scopes, path and query parameters, request body, success response, error responses, rate limits and an example. Include the idempotency behaviour for side-effecting endpoints and the pagination style for collections.
Example: POST /v1/orders creates an order. It requires an idempotency key, returns 201 with a Location header, returns 422 with field-level validation errors and returns 409 if the customer reference conflicts. The documentation should show each of those responses, not just the happy path.
Where this fits in our work
If you need an API designed or reviewed, start with Custom Software & Integrations. The pricing page explains scope. For the build-versus-buy decision, read when custom software is the right decision.
Sources
- OWASP API Security Top 10, 2023, accessed 16 November 2026.
- Microsoft REST API Guidelines, accessed 16 November 2026.
- Google API Design Guide, accessed 16 November 2026.
- RFC 9457, Problem Details for HTTP APIs, 2023.
- RFC 9110, HTTP Semantics, 2022.
Responses (0)
No comments yet. Add the first one below.
Leave a response
Your email address will not be published. Required fields are marked *.