EP161: A Cheatsheet on REST API Design Best Practices

This cheatsheet provides a concise guide to REST API design principles, covering best practices for endpoints, HTTP methods, status codes, versioning, authentication, and error handling. It emphasizes simplicity, consistency, and scalability while addressing common pitfalls in API development.

---

Core Technical Concepts/Technologies

• REST (Representational State Transfer)
• HTTP methods (GET, POST, PUT, DELETE, PATCH)
• API versioning (URL, headers)
• Authentication (JWT, OAuth, API keys)
• Error handling (HTTP status codes, custom error messages)
• Pagination, filtering, sorting

---

Main Points

• Endpoint Design:

  • Use nouns (e.g., /users) instead of verbs.
  • Keep URLs hierarchical (e.g., /users/{id}/posts).
  • Use lowercase and hyphens for readability.

• HTTP Methods:

  • GET for retrieval, POST for creation, PUT/PATCH for updates, DELETE for removal.
  • PUT replaces entire resources; PATCH updates partial fields.

• Status Codes:

  • 2xx for success, 4xx for client errors, 5xx for server errors.
  • Common codes: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 404 (Not Found).

• Versioning:

  • URL-based (e.g., /v1/users) or header-based (Accept: application/vnd.api.v1+json).
  • Avoid breaking changes; deprecate old versions gracefully.

• Authentication:

  • Prefer OAuth2 or JWT for security.
  • API keys for simpler use cases (rate-limited).

• Error Handling:

  • Return structured errors with codes, messages, and details.
  • Example:

    { "error": { "code": 404, "message": "User not found" } }
    

• Pagination/Filtering:

  • Use limit, offset, or cursor-based pagination.
  • Filter via query params (e.g., /users?role=admin).

---

Key Takeaways

1. Consistency: Follow REST conventions (nouns, HTTP methods) for predictable APIs.
2. Security: Use standardized authentication (OAuth2/JWT) and avoid sensitive data in URLs.
3. Clarity: Provide meaningful status codes and error messages for debugging.
4. Scalability: Implement pagination and versioning early to handle growth.
5. Maintainability: Document APIs thoroughly and deprecate versions systematically.

---

Limitations/Caveats

• REST may not suit real-time applications (consider WebSockets/gRPC).
• Over-fetching/under-fetching can occur; GraphQL is an alternative.
• Versioning requires careful planning to avoid fragmentation.