RESTful API Best Practices

This document outlines essential best practices for designing and implementing RESTful APIs. Adhering to these principles ensures your API is consistent, predictable, scalable, and easy for developers to integrate with.

1. Use Nouns for Resources, Not Verbs

REST is resource-oriented. Your API endpoints should represent the resources available, not the actions to be performed on them. Use HTTP methods to indicate the action.

Good: GET /users (Retrieve a list of users)
Good: GET /users/{id} (Retrieve a specific user)
Good: POST /users (Create a new user)
Good: PUT /users/{id} (Update a specific user)
Good: DELETE /users/{id} (Delete a specific user)
Bad: GET /getAllUsers
Bad: POST /createNewUser

2. Leverage HTTP Methods Correctly

HTTP methods (verbs) have standard meanings and should be used appropriately:

GET: Retrieve data. Should be idempotent and safe (no side effects).
POST: Create a new resource or trigger a process. Not necessarily idempotent.
PUT: Update an existing resource (replace entirely). Idempotent.
PATCH: Partially update an existing resource. Not necessarily idempotent.
DELETE: Remove a resource. Idempotent.

Tip: For operations that don't map cleanly to CRUD (Create, Read, Update, Delete), consider creating a specific resource for that action, e.g., POST /users/{id}/send-reset-email.

3. Use Plural Nouns for Collections

Resource collections should be represented by plural nouns. Individual resources within a collection are identified by their unique ID.

/products (Collection of products)
/products/123 (Specific product with ID 123)
/orders (Collection of orders)
/orders/abc (Specific order with ID abc)

4. Use HTTP Status Codes Appropriately

Status codes provide crucial information about the outcome of a request. Use them consistently.

2xx Success:
- 200 OK: Request successful.
- 201 Created: Resource successfully created (often used with POST).
- 204 No Content: Request successful, but no response body (e.g., DELETE).
3xx Redirection:
- 301 Moved Permanently
- 302 Found
4xx Client Error:
- 400 Bad Request: Invalid request syntax or parameters.
- 401 Unauthorized: Authentication is required and has failed or not been provided.
- 403 Forbidden: Authenticated but lacks permission.
- 404 Not Found: Resource not found.
- 405 Method Not Allowed: HTTP method not supported for this resource.
- 409 Conflict: Request conflicts with the current state of the resource.
- 429 Too Many Requests: Rate limiting.
5xx Server Error:
- 500 Internal Server Error: Generic server error.
- 503 Service Unavailable: Server is temporarily overloaded or down.

Tip: Always provide a meaningful error message in the response body for client errors (4xx) and server errors (5xx).

5. Support Filtering, Sorting, and Pagination

For collections, enable clients to refine results efficiently.

Filtering

Use query parameters to filter resources.

GET /products?category=electronics
GET /users?status=active&role=admin

Sorting

Use query parameters to specify sorting order.

GET /products?sort=price:asc
GET /users?sort=-createdAt (Descending order)

Pagination

Implement pagination to avoid returning massive datasets.

GET /products?page=2&limit=50
GET /users?offset=100&count=25

Important: Include pagination metadata in the response, such as total count, links to next/previous pages, and current page information.

{
    "data": [ ... ],
    "pagination": {
        "totalItems": 1000,
        "currentPage": 2,
        "itemsPerPage": 50,
        "totalPages": 20,
        "nextPage": "/products?page=3&limit=50",
        "previousPage": "/products?page=1&limit=50"
    }
}

6. Version Your API

APIs evolve. Versioning allows you to introduce breaking changes without affecting existing clients.

URI Versioning: /v1/users, /v2/users (Most common)
Header Versioning: Accept: application/vnd.yourapi.v1+json
Query Parameter Versioning: /users?version=1

Tip: URI versioning is generally the most straightforward for discoverability and tooling.

7. Use JSON for Request and Response Bodies

JSON is the de facto standard for web APIs due to its simplicity and widespread support.

Set the Content-Type and Accept headers appropriately:

Content-Type: application/json
Accept: application/json

8. HATEOAS (Hypermedia as the Engine of Application State)

Include links within responses to guide clients to related resources and possible actions. This makes your API more discoverable and less coupled.

{
    "id": 123,
    "name": "Example Product",
    "price": 99.99,
    "_links": {
        "self": { "href": "/products/123" },
        "category": { "href": "/categories/45" },
        "reviews": { "href": "/products/123/reviews" }
    }
}

9. Secure Your API

Implement robust security measures:

Authentication: Use standard methods like OAuth 2.0, API Keys, or JWTs.
Authorization: Ensure users only access resources they are permitted to.
HTTPS: Always use HTTPS to encrypt data in transit.
Rate Limiting: Protect against abuse and denial-of-service attacks.
Input Validation: Sanitize and validate all incoming data to prevent injection attacks.

10. Documentation

Clear, comprehensive, and up-to-date documentation is crucial for API adoption. Use tools like Swagger/OpenAPI to generate interactive documentation.