REST API Design Best Practices for Product Teams

Resource Naming and URL Structure

Resource naming is the foundation of API usability. Use plural nouns for collection endpoints -- /users, /orders, /products -- and nest related resources logically: /users/123/orders returns orders for user 123. Avoid verbs in URLs because the HTTP method communicates the action. GET /users retrieves users, POST /users creates one. Microsoft's REST API guidelines, adopted by Azure and Office 365, formalize this pattern.

Keep URLs shallow. Deep nesting like /companies/5/departments/3/employees/42/reviews creates coupling between resources and makes the API brittle. If a review can be fetched by its own ID, /reviews/42 is simpler and more flexible. Use query parameters for filtering rather than encoding every relationship in the URL path.

Be consistent with naming conventions. If you use camelCase for one endpoint's response fields, use it everywhere. If you abbreviate 'organization' to 'org' in one URL, do it in all URLs. Stripe's API is widely cited as a model of naming consistency -- every endpoint follows the same patterns, making the API predictable even for endpoints a developer has not used before.

HTTP Methods and Status Codes Done Right

Use HTTP methods according to their defined semantics. GET is safe and idempotent -- it never modifies data. PUT replaces a resource entirely and is idempotent. PATCH partially updates a resource. DELETE removes a resource. POST creates a new resource or triggers a process. Misusing methods -- using POST for retrieval or GET for deletion -- breaks client expectations and caching behavior.

Return appropriate status codes. 200 for successful GET/PUT/PATCH. 201 for successful POST that creates a resource, with a Location header pointing to the new resource. 204 for successful DELETE with no response body. 400 for malformed requests. 401 for missing authentication. 403 for insufficient permissions. 404 for resources that do not exist. 422 for validation errors. 429 for rate limiting.

The distinction between 400, 422, and 409 matters for client developers. A 400 means the request is syntactically invalid -- malformed JSON or missing required headers. A 422 means the request is well-formed but fails business validation -- an email field without an @ sign. A 409 means the request conflicts with current state -- trying to create a username that already exists. These distinctions help client developers write precise error handling logic.

Error Response Design

Error responses should be as carefully designed as success responses. Include a machine-readable error code, a human-readable message, and a field-level breakdown for validation errors. Twilio's API returns errors in a consistent format: a numeric error code, a message describing what went wrong, and a documentation URL linking to detailed troubleshooting guidance. This pattern dramatically reduces support ticket volume.

Never expose internal implementation details in error messages. A database constraint violation should not surface as 'UNIQUE constraint failed: users.email' in the API response. Translate internal errors into user-meaningful messages like 'An account with this email address already exists.' Internal details leak information that can be used for attacks and confuse API consumers.

For validation errors on multiple fields, return all errors at once rather than one at a time. A request that submits an invalid email and a missing required field should return both errors in a single response, allowing the client to fix everything in one round trip. JSON:API and Problem Details (RFC 9457) both define standard formats for multi-error responses.

Pagination, Filtering, and Sorting

Any endpoint that returns a collection needs pagination. Cursor-based pagination using opaque tokens is more reliable than offset-based pagination for datasets that change frequently. Offset pagination breaks when items are inserted or deleted between pages -- users see duplicates or miss items. Cursor pagination maintains a stable position regardless of concurrent modifications. Slack, Facebook, and GitHub all use cursor-based pagination.

Filtering should use query parameters with consistent naming. Support exact match (/users?status=active), range queries (/orders?created_after=2025-01-01), and inclusion lists (/products?category=shoes,boots). Document which fields support filtering and which operators are available. Limit filterable fields to those backed by database indexes to prevent performance problems.

Sorting follows a similar pattern: /products?sort=price or /products?sort=-created_at for descending order. Support multi-field sorting with comma separation: /products?sort=-featured,price sorts by featured status descending, then by price ascending. The JSON:API specification defines a standard for sort parameters that many API teams adopt as a convention.

Authentication and Rate Limiting

API authentication should use OAuth 2.0 for user-delegated access and API keys for server-to-server communication. Bearer tokens in the Authorization header are the standard transport mechanism. Never accept API keys in URL query parameters -- they leak into server logs, browser history, and referrer headers. The OWASP API Security Top 10 lists broken authentication as the number one API vulnerability.

Rate limiting protects the API from abuse and ensures fair resource allocation across consumers. Return rate limit status in response headers: X-RateLimit-Limit for the maximum requests per window, X-RateLimit-Remaining for requests left, and X-RateLimit-Reset for when the window resets. When the limit is exceeded, return 429 Too Many Requests with a Retry-After header.

Apply different rate limits to different endpoint categories. Read endpoints can typically handle higher rates than write endpoints. Search endpoints are often the most expensive and should have the lowest limits. Consider per-endpoint limits rather than a single global limit so that a consumer hitting the search rate limit can still make read requests. Provide higher limits for authenticated requests to incentivize proper authentication.