RESTful API Design Cheatsheet

RESTful API design is a complex process that involves many factors, including scalability, performance, security, and user experience. This cheat sheet provides a quick reference for best practices and common pitfalls to avoid when designing RESTful APIs.

HTTP request methods

HTTP request methods/HTTP verbs are used to perform operations on resources in a RESTful API. Each HTTP verb has a specific purpose, and using them correctly is essential for API consistency and security. Here are the most common HTTP verbs and their usage:

• GET: retrieve a resource
• POST: create a new resource or perform an action on a resource
• PUT: update an existing resource
• PATCH: partially update an existing resource
• DELETE: delete a resource

Naming Conventions

Resource naming conventions are crucial for API readability and usability.

• Use plural nouns for collections of resources (e.g., /users)
• Use singular nouns for individual resources (e.g., /users/123)
• Use lowercase letters and hyphens for resource names (e.g., /users/123/orders)
• Use nouns instead of verbs in resource names (e.g., /orders/123 instead of /get-order/123)

Resource Pagination

Resource pagination is necessary when dealing with large collections of resources.

• Use limit and offset parameters for pagination (e.g., /users?limit=10&offset=20)
• Use a default limit and let the client control the offset
• Include pagination metadata in the response headers (e.g., X-Total-Count)

Error Responses

Error responses are crucial for API usability and should be consistent across the API.

Use HTTP status codes to indicate the error type (e.g., 400 for bad request, 401 for unauthorized, 404 for not found, 500 for internal server error)

• Include a descriptive error message in the response body
• Use a consistent error format across the API

Authentication and Authorization

Authentication and authorization are essential for API security.

• Use a secure authentication mechanism (e.g., OAuth 2.0, JWT)
• Use HTTPS for secure communication
• Use role-based access control (RBAC) to restrict access to resources
• Use appropriate scopes to restrict access to specific actions

Versioning

API versioning is necessary when changes are made to the API, and backward compatibility needs to be maintained.

• Use a version number in the URI (e.g., /v1/users)
• Use a version header in the request (e.g., Accept-Version: v1)
• Deprecate old versions and provide a migration path

Caching

Caching can improve API performance and reduce server load. Here are some best practices for API caching:

• Use appropriate cache headers (e.g., Cache-Control, Expires)
• Use ETags for resource validation
• Consider using a content delivery network (CDN) for caching

HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) is a RESTful API design principle that enables clients to discover and interact with resources dynamically.

• Include links to related resources in the response
• Use standard link relations (e.g., self, next, prev)
• Use media types that support hypermedia (e.g., HAL, JSON-LD)

Filtering and Sorting

• Use query parameters for filtering (e.g., /users?status=active)
• Use query parameters for sorting (e.g., /users?sort=name_asc)

Rate Limiting

• Use HTTP headers to communicate rate limits (e.g., X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
• Apply rate limiting based on client IP, authenticated user, or API key

Content Negotiation

• Use the Accept header to specify desired response format (e.g., application/json)
• Use the Content-Type header to specify the format of the request payload (e.g., application/json)

API Documentation

• Provide clear and comprehensive documentation
• Use tools like Swagger/OpenAPI or RAML for API documentation
• Include examples for different request scenarios

CORS (Cross-Origin Resource Sharing)

• Implement CORS headers to control which domains can access your API
• Use Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, and Access-Control-Max-Age headers as needed
• Ensure that preflight requests (OPTIONS) are properly handled

API Monitoring and Testing

I have recently been using a service called Checkly, combined with Instatus for my API monitoring/status alerting. You can view my status page here.

• Monitor API performance and uptime
• Use tools like Postman, Insomnia, or curl for manual testing
• Implement automated testing for critical API functionality

I put together this REST API cheatsheet to assist with the production/planning of my own API documentation, hopefully it is useful for someone reading.