REST API Design Checklist

A REST API design checklist helps backend teams review an endpoint before clients depend on it.

The goal is not to make every endpoint look identical. The goal is to make the contract predictable enough that client developers can call it, retry it, paginate it, debug it, and survive future changes.

Quick answer

Before publishing a REST API endpoint, check:

• Resource naming.
• HTTP method semantics.
• Request body shape.
• Response body shape.
• Status codes.
• Error format.
• Authentication and authorization.
• Pagination, filtering, and sorting.
• Idempotency and retry behavior.
• Rate limits.
• Versioning and compatibility.
• OpenAPI documentation and examples.
• Observability fields such as request IDs.

This checklist is most useful during API design reviews, pull requests, and release readiness checks.

1. Resource and URL design

REST APIs work best when URLs represent resources.

Good resource paths are stable nouns:

GET /users/{userId}
GET /orders/{orderId}
GET /accounts/{accountId}/invoices

Avoid hiding unclear commands inside resource paths:

POST /orders/{orderId}/doCancelAndRefundNow

Some operations really are commands. That is fine, but be honest about the style. Read REST vs RPC before forcing every workflow into a resource shape.

Checklist:

• Is the URL centered on a resource?
• Are path parameters named clearly?
• Are plural nouns used consistently?
• Is the endpoint style consistent with nearby endpoints?

2. HTTP method semantics

Choose methods deliberately.

Method	Common use
GET	Read a resource or list
POST	Create a resource or start a command
PUT	Replace a resource
PATCH	Partially update a resource
DELETE	Delete or deactivate a resource

Do not use GET for operations with side effects. Clients, caches, crawlers, and observability tools expect GET to be safe.

Read PUT vs PATCH in REST APIs when defining update behavior.

3. Request body design

Request bodies should be explicit and stable.

Checklist:

• Are required fields documented?
• Are optional fields documented?
• Are enum values listed?
• Are timestamps and time zones clear?
• Are IDs string or numeric consistently?
• Are unknown fields ignored or rejected?
• Are validation rules documented?

Avoid accepting a field just because the database has a column. API shape should match client intent, not internal persistence layout.

4. Response body design

A response body should tell clients what happened and what they can do next.

For resource reads, return the resource representation:

{
  "id": "ord_123",
  "status": "paid",
  "totalCents": 4200
}

For create requests, decide whether to return the created resource, a status object, or a location header.

Checklist:

• Is the response shape stable?
• Are nullable fields intentional?
• Are timestamps consistently formatted?
• Are IDs stable and documented?
• Are examples realistic?
• Can clients tolerate future optional fields?

5. Status codes

Use HTTP status codes as the first contract signal.

Common choices:

• 200 OK for successful reads and updates with bodies.
• 201 Created for successful creates.
• 202 Accepted for async work.
• 204 No Content for success without a body.
• 400 or 422 for validation failures.
• 401 for missing or invalid authentication.
• 403 for denied authorization.
• 404 for missing or hidden resources.
• 409 for conflicts.
• 429 for rate limits.
• 500 and 503 for server failures.

Read REST API Status Codes Explained for details.

6. Error contract

Every endpoint should use the shared error shape.

Example:

{
  "error": "validation_failed",
  "message": "One or more fields are invalid.",
  "fields": {
    "email": "Enter a valid email address."
  },
  "requestId": "req_123"
}

Checklist:

• Is the error code stable?
• Is the message safe for users?
• Are field errors structured?
• Is requestId included?
• Are internal exceptions hidden?
• Are retryable errors documented?

Read REST API Error Handling Best Practices for the deeper pattern.

7. Pagination, filtering, and sorting

List endpoints need bounded behavior.

Checklist:

• Is there a documented limit?
• Is there a maximum page size?
• Is the sort order stable?
• Is there a unique tie-breaker?
• Are filters documented?
• Are cursors opaque when cursor pagination is used?
• Does the response include clear page metadata?

For response metadata details, read API Pagination Metadata Best Practices.

8. Idempotency and retries

Clients retry after timeouts, network errors, and server failures. The API should define what happens when the same request is sent twice.

Checklist:

• Are GET, PUT, and DELETE idempotent in practice?
• Do risky POST operations support idempotency keys?
• Are retryable status codes documented?
• Are duplicate requests safe?
• Does the response include enough information for clients to recover?

Read Idempotency in APIs Explained and Retry Patterns Explained before asking clients to retry writes.

9. Authentication and authorization

Authentication proves who the caller is. Authorization decides what the caller can do.

Checklist:

• Is authentication required?
• Which token, API key, or session mechanism is used?
• Which scopes or permissions are required?
• Are object ownership and tenant boundaries checked?
• Are 401 and 403 used consistently?
• Are sensitive failures logged safely?

For credential tradeoffs, read API Key vs OAuth Token.

10. Versioning and compatibility

Changing an API after clients depend on it is expensive.

Checklist:

• Is this change backward-compatible?
• Are new response fields optional?
• Are old fields preserved?
• Are enum expansions safe?
• Are deprecations documented?
• Does OpenAPI diff or contract review catch breaking changes?

Read API Versioning Explained before changing a published contract.

11. OpenAPI and examples

A REST endpoint is not ready until the contract is visible.

Checklist:

• Is the endpoint in OpenAPI?
• Are request and response schemas documented?
• Are error responses documented?
• Are examples realistic?
• Are pagination and auth documented?
• Are operation IDs stable if SDKs use them?

Read OpenAPI Explained for Backend Developers and JSON Schema vs OpenAPI Schema for schema boundaries.

12. Observability and support

Production APIs need debugging paths.

Checklist:

• Does every request get a request ID?
• Are important events logged without secrets?
• Are rate limits observable?
• Are validation failures measurable?
• Can support connect a user report to logs?
• Are audit logs needed for sensitive actions?

Use the UUID Generator for request ID examples and the HTTP Status Code Lookup while reviewing response behavior.

Common mistakes

The first mistake is reviewing only the happy path. Clients need error cases, empty states, limits, and retries.

The second mistake is letting every endpoint invent its own response shape.

The third mistake is treating pagination, sorting, and filtering as UI details. They are API contract details.

The fourth mistake is publishing OpenAPI without examples.

The fifth mistake is changing status codes, field names, or pagination behavior without migration notes.

Practical recommendation

Use this checklist before exposing a new endpoint to clients.

For small teams, keep the review lightweight:

• One endpoint owner.
• One client-minded reviewer.
• One OpenAPI diff or schema review.
• One pass through status codes, errors, pagination, retries, auth, and examples.

The best API contracts are boring in the right way: predictable, documented, observable, and hard to accidentally break.

Related reading

Read Spring Boot REST Controller Explained, REST vs RPC, OpenAPI Explained for Backend Developers, REST API Status Codes Explained, and REST API Error Handling Best Practices before publishing a public API.

For list endpoints, read Pagination Strategies for REST APIs and API Pagination Metadata Best Practices. For the full sequence, browse the API Design Learning Path and the Topics map.