Building Better REST APIs: Best Practices and Cheat Sheet

by

Building Better REST APIs: Best Practices and Cheat Sheet

Designing REST APIs is both an art and a science. A well-designed API can save developers countless hours, streamline integrations, and ensure your system is scalable and maintainable. But how do you design one that stands out? Let’s dive into the best practices that will help you create intuitive, secure, and high-performing REST APIs.

Why REST API Design Matters

Imagine an app with millions of users relying on your API for data. Every poorly designed endpoint adds friction, and every inconsistency leads to confusion. A poorly performing API can cost you customers or even the trust of your developers. Getting it right isn’t just a bonus—it’s a necessity.

In my experience, API downtimes, while being caused by infrastructure defects, are also often caused by poor design and security decisions. By following the practices below, you’ll not only avoid these pitfalls but also create APIs that developers love.

1. Use Clear and Consistent Resource Naming

Best Practices:

  • Use nouns, not verbs: Resources should represent entities, not actions.
    • Good: /users
    • Bad:/getUsers
      • Note: HTTP already has methods/verbs. i.e. GET /users will indicate appropriate action against this entity
  • Follow a hierarchy: Reflect relationships in your URIs.
    • Example:
      • /orders for all orders
      • /orders/{orderId} for a specific order
      • /orders/{orderId}/items for items in a specific order
  • Stick to lowercase: Use lowercase and hyphens instead of underscores.
    • Good: /user-profiles
    • Bad: /User_Profiles
  • Avoid Verbs in URIs: Ensure URIs focus on resources, not actions. This aligns with REST principles and makes APIs intuitive.

2. Leverage HTTP Methods Appropriately

Each HTTP method has a clear purpose. Use them consistently:

MethodPurposeExample
GETRetrieve resources/users
POSTCreate a resource/users
PUTUpdate or replace/users/{userId}
PATCHPartially update/users/{userId}
DELETERemove a resource/users/{userId}

Pro Tip: PUT is idempotent; POST is not. Understand the difference to avoid issues. Meaning, if you execute PUT multiple times you will have a single result, while executing POST multiple times should result in multiple entries.

3. Provide Meaningful HTTP Status Codes

Don’t leave clients guessing. Use standard HTTP status codes to indicate the result of requests.

Status CodeMeaningUse Case
200OKSuccessful GET or POST
201CreatedResource successfully created
204No ContentSuccessful DELETE without a response
400Bad RequestInvalid input from the client
401UnauthorizedAuthentication required
404Not FoundResource does not exist
500Internal Server ErrorServer-side issue

4. Implement API Versioning

Breaking changes are inevitable. Versioning ensures backward compatibility.

Strategies:

  • URI Versioning: Add the version number to the endpoint.
    • Example: /api/v1/users
  • Header Versioning: Include version in request headers.
    • Example: Accept: application/vnd.company.v1+json

Tip: URI versioning is more common and user-friendly.

What if there is no versioning?

In real-world scenarios, you might encounter production APIs that lack versioning. While this situation can be challenging, here are strategies to manage it:

  • Understand the Risk of Breaking Changes: Even fixing bugs in a non-versioned API can be a breaking change. While some customers will benefit from the fix, others may have workarounds in place that your fix will disrupt. Always proceed with caution and communicate changes clearly.
  • Introduce Headers for Compatibility: Work with the API provider to introduce versioning through headers, e.g., X-API-Version.
  • Consider the Non-Versioned API as Version 1: Treat the existing API as version 1 and introduce future changes under a new version. Never alter the URL structure for the legacy API.
  • Document Current Behavior: Maintain detailed documentation of the API’s current state to manage expectations and prepare for potential breaking changes.
  • Use API Gateways: Implement an API gateway to abstract changes and provide stability for downstream consumers.

These approaches can help maintain stability while working with non-versioned APIs.

5. Enhance Usability with Filtering, Sorting, and Pagination

APIs should empower users to query data effectively:

  • Filtering: Use query parameters.
    • Example: /users?role=admin
  • Sorting: Allow sorting by fields.
    • Example: /users?sort=name_asc
  • Pagination: Return data in chunks.
    • Example: /users?page=2&limit=50

Note: Use metadata to inform clients about total results and pages. Consider including pagination details in response headers, such as X-Total-Count to indicate the total number of resources available.

6. Prioritize Security

Steps to Secure Your API:

  • Use HTTPS: Always encrypt data in transit.
  • Authentication: Implement OAuth 2.0 or JWT for secure access.
  • Rate Limiting and Throttling: Protect against abuse by limiting the number of requests and defining thresholds for usage. Communicate these limits using headers like X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to inform clients of their current rate limits and when they reset.
  • Input Validation: Sanitize and validate all client inputs to prevent SQL injection and other attacks.

7. Provide Clear and Consistent Documentation

Documentation is the first step to developer adoption.

  • OpenAPI (formerly Swagger): Use OpenAPI to auto-generate interactive and up-to-date documentation.
  • Static vs. Dynamic Documentation: Static documentation explains relationships, business logic, and overarching concepts, while dynamic documentation details API endpoints and usage examples.
  • Interactive Environments: Provide interactive sandboxes where developers can test API endpoints in real-time.
  • Document Cross-Referenced Parameters: Clearly outline parameter relationships, especially those that are interdependent, to reduce confusion and integration errors.
  • Include Examples: Provide request and response examples for each endpoint.
  • Error Codes: Document every possible error code and its meaning.

8. Handle Errors Gracefully

Developers need actionable error messages to debug effectively.

Error Format Example:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The 'email' field is required."
  }
}

Best Practices:

  • Consistency: Follow a standardized format.
  • Clarity: Provide actionable error descriptions.
  • Use the Appropriate Content-Type: Always set the Content-Type: application/json header to ensure clients can properly parse the response.

9. Optimize Performance

Strategies:

  • Caching: Use Cache-Control headers and ETags to minimize redundant requests.
    • Example: When a client requests a resource (e.g., /users), include an ETag header in the response. The client can use this ETag in subsequent requests to check if the resource has changed, avoiding unnecessary data transfers.
  • Compression: Enable gzip compression to reduce payload sizes.
    • Example: Configure your server to compress JSON responses using gzip. For instance, a /users response of 100KB could compress to 20KB, significantly reducing bandwidth usage.
  • Database Optimization: Index frequently queried fields.
    • Example: For a /users?role=admin query, ensure the role field in the users table is indexed to speed up filtering and reduce query execution time.
  • Asynchronous Operations: For long-running processes, return a 202 Accepted status and include a URL where the client can check the operation’s progress.
    • Example: If processing a large file upload via /files/upload, immediately return a 202 Accepted response with a link like /files/status/{uploadId} for the client to monitor the process.

10. Advanced Considerations: Hypermedia as the Engine of Application State (HATEOAS)

Hypermedia (HATEOAS) enables dynamic navigation of the API through links included in responses. This approach ensures that clients don’t need hardcoded knowledge of endpoints, making APIs more flexible and easier to evolve.

Example Response with HATEOAS:

{
  "id": 123,
  "name": "John Doe",
  "links": [
    { "rel": "self", "href": "/users/123" },
    { "rel": "orders", "href": "/users/123/orders" },
    { "rel": "next", "href": "/users?page=3" },
    { "rel": "prev", "href": "/users?page=1" }
  ]
}

11. Content Negotiation

APIs should support multiple response formats and allow clients to specify their preference using the Accept header. For example:

  • Accept: application/json
  • Accept: application/xml

Always return responses in the format requested by the client, and ensure the Content-Type header matches the response payload.

Conclusion

Designing a great REST API takes effort, but the rewards are worth it. By adhering to these best practices, you can create APIs that are intuitive, secure, and a joy to work with. Remember, your API is a product—treat it as such.

Ready to get started? Audit your current API design against this cheat sheet and see how you stack up. Let’s build better APIs together!