Skip to content
EncryptTechBD
Home Industries Our Work Blog Pricing About Contact Discuss Your Project
বাংলা (BN)
Software Engineering 6 min read

REST API design checklist for business systems

A practical REST API checklist: resources, HTTP semantics, errors, pagination, idempotency, auth, rate limits, observability and documentation.

E
EncryptTechBD · 0 comments
Laptop with code in a workspace
Photo: Matthew Henry / StockSnap

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}/orders is 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 /v1 is simple and visible; header versioning is also valid but harder to test.

HTTP semantics

  • Use GET for safe reads, POST for creation or actions, PUT for full replacement, PATCH for partial updates and DELETE for removal.
  • Return the correct status code: 201 with a Location header for creation, 204 for a successful empty response, 400 for invalid input, 401 for missing authentication, 403 for missing permission, 404 for not found, 409 for conflict, 422 for semantic validation and 429 for rate limits.
  • Do not return 200 with an error body. Clients and monitoring tools rely on status codes.
  • Use ETag and If-Match for optimistic concurrency where two users can edit the same record.
  • Honour Idempotency-Key for 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 /orders may 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 429 with a Retry-After header.
  • 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

Services that deliver this

Want this implemented properly?

Pricing →

Every engagement starts with a written scope. If a requirement is outside it, we quote it separately before starting.

Responses (0)

No comments yet. Add the first one below.

Leave a response

Your email address will not be published. Required fields are marked *.

Keep reading

More field notes