REST API Design Best Practices — Build APIs Developers Will Love

What Makes a Good REST API Design?

A well-designed REST API is intuitive, consistent, and self-describing. Consumers should be able to predict endpoint behavior from the URL and method. REST API design best practices have been refined through thousands of public APIs — this guide distills the patterns that work.

URL Design and Resource Naming

1. Use nouns, not verbs — /users not /getUsers; the HTTP method provides the verb.
2. Use lowercase and hyphens — /user-profiles not /UserProfiles or /user_profiles.
3. Use plural nouns — /users, /orders, /products for consistency.
4. Represent hierarchy with path segments — /users/123/orders for a user's orders.
5. Keep URLs short — avoid more than 3 levels of nesting; flatten with query parameters if needed.

Key REST API Design Principles

Versioning

Version your API from day one. Common approaches:

• URL versioning: /v1/users — simple, visible, cacheable. Most widely used.
• Header versioning: Accept: application/vnd.api+json;version=1 — cleaner URLs but harder to test in browser.
• Query parameter: /users?version=1 — simple but less conventional.

Consistent Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email address is invalid",
    "field": "email",
    "status": 422
  }
}

Always return a consistent error shape. Include a machine-readable code, human-readable message, and HTTP status. Use standard status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 422 (validation error), 429 (rate limited), 500 (server error).

Pagination

GET /users?page=2&per_page=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Never return unbounded lists. Use cursor-based pagination for real-time feeds and large datasets; offset pagination for admin tables and reports.

Authentication

Use Bearer tokens in the Authorization header: Authorization: Bearer <token>. For public APIs, implement OAuth 2.0. For internal APIs, API keys or JWTs are simpler. Always use HTTPS — never send credentials over plain HTTP.

Use Cases

Public Developer APIs

APIs consumed by third-party developers (like Stripe or Twilio) require especially careful design. Good REST API design best practices applied here result in lower support burden, better adoption, and fewer breaking changes.

Mobile Backend APIs

Mobile apps often request specific data shapes to minimize bandwidth. Design endpoints that serve the mobile client's exact needs, use sparse fieldsets (?fields=id,name,email), and implement aggressive caching headers.

Frequently Asked Questions

Should I use plural or singular nouns in REST API URLs?

Use plural nouns consistently: /users, /products, /orders. This makes the pattern predictable — a collection is always plural, and an individual resource is the plural noun with an ID: /users/123.

How do I handle filtering in REST APIs?

Use query parameters for filtering: /users?status=active&role=admin. For complex filtering, consider a filter object: /users?filter[status]=active. Document all supported filter fields explicitly.

Should I return 200 or 204 for a successful DELETE?

204 No Content is most common and semantically correct — deletion succeeded and there's nothing to return. Some teams prefer 200 with a confirmation message. Consistency within your API matters more than which you choose.

How should I handle nested resources in REST APIs?

Use path nesting sparingly: /users/123/orders is fine for directly related resources. Avoid deep nesting like /users/123/orders/456/items/789/reviews — flatten with standalone resource endpoints like /reviews/review-id instead.

How do I implement rate limiting in a REST API?

Return rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Return HTTP 429 when limits are exceeded with a Retry-After header. Implement per-user or per-API-key limits, not just per-IP.