12 REST API Best Practices to follow in 2023

As a developer, you understand the importance of having an API that is reliable, secure and easy to use. By following REST API best practices, you can make sure your API meets these standards.

I've been developing APIs for over 10 years and here's my list of most important REST API best practices:

1. Follow the URI Naming Conventions

URIs in REST APIs should follow specific naming conventions for consistency and clarity.

2. Use HTTP methods to communicate intent

One of the key principles of REST APIs is the use of standard HTTP methods to communicate the intent of the request.

Read more: PATCH VS PUT

Do not use verbs in the URI.

Here's an example of what to do and not to do:

3. Use appropriate data structure

It's a common misconception that REST API must use JSON structure. But REST is all about a resource. That resource can be a JPEG image, HTML document, or any data structure.

Find out what works for you. A lot of company API guidelines force the use of JSON.

Valid JSON schema

If you use JSON, follow these best practices:

1. Valid JSON Schema should be used for both request and response bodies.
2. Include the "Content-Type" header set to "application/json" in all requests and responses when sending JSON data.
3. Use JSON even when communicating error messages. Don't just return plain text or HTML.

4. Pick your JSON field naming convention (and stick to it)

JSON standard doesn't impose a field naming convention, but it's a best practice to pick one and stick with it.

camelCase and snake_case are the most common. I prefer camelCase and I don't recommend PascalCase or kebab-case.

5. Communicate with HTTP status codes

Status codes are a standard part of the HTTP protocol, and they allow you to quickly convey information about the outcome of a request.

By using HTTP status codes in your API responses, you help your clients build their error handling.

Here is a table that lists the most important HTTP status codes:

Read more: HTTP Bad Request vs Not Found

6. Do not maintain state

A REST API should not maintain state on the server. That's the responsibility of the client.

This is important because it allows for the API to be cacheable, scalable, and decoupled from the client.

For example, an ecommerce API might use cookies to maintain the state of a shopping cart. However, such approach violates key the key principle of RESTful APIs - they need to be stateless.

7. Version your APIs

API Versioning is important because it allows for backward compatibility, enables the introduction of new features without breaking existing clients, and allows for phased rollouts of changes.

Here are the most popular ways to version a REST API:

The URL path versioning method is the most popular because it is easy to see which version of the API you're using by just looking at the URL.

When should I introduce a new version of an API endpoint?

A new version of an API endpoint should be introduced when there is a change that is not backward compatible with previous versions.

This could include changes to the request or response format, changes to the resource being accessed, or changes to the expected behavior of the endpoint. Additionally, a new version may be introduced if a major overhaul or redesign of the endpoint is needed.

It's important to version the API so that existing clients can continue to work with previous versions while new clients can take advantage of the new functionality.

8. Document your API thoroughly

Thoroughly documenting an API involves several key steps:

1. Create concise API documentation: Include all of the endpoints with their request and response bodies.
2. Provide code examples: Include examples in multiple programming languages to demonstrate how the API can be used.
3. Use clear and descriptive error messages: Clearly communicate what errors may occur and how to handle them.
4. Offer interactive documentation: Use tools like Swagger UI or Postman to provide an interactive documentation experience for developers.
5. Document security: Explain how the API can be secured and what kind of authentication is required.
6. Explain rate limiting: Clearly communicate any rate limits and how they are enforced.
7. Offer detailed release notes: Keep developers informed of any changes or updates to the API.
8. Provide support resources: Offer resources such as a developer forum or support center to help developers with any questions they may have.
9. Regularly update documentation: Regularly update the documentation to ensure it remains accurate and relevant.

9. Use consistent error messages

In most cases, HTTP status codes are not enough to explain what went wrong.

To help your API consumers, include a structured JSON error message.

The response should include the following information:

1. Error code: A machine-readable error code that identifies the specific error condition.
2. Error message: A human-readable message that provides a detailed explanation of the error.
3. Error context: Additional information related to the error, such as the request ID, the request parameters that caused the error, or the field(s) in the request that caused the error.
4. Error links: URLs to resources or documentation that provide additional information about the error and how it can be resolved.
5. Timestamp: The time when the error occurred.

Figure out what works for you and stick to it. Every error message in your API should follow the same format.

For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errorCode": "INVALID_INPUT",
    "message": "The input provided is invalid.",
    "details": [
        {
            "field": "firstName",
            "issue": "required field is missing"
        },
        {
            "field": "lastName",
            "issue": "required field is missing"
        }
    ],
    "request_id": "5124129901",
    "timestamp": "2022-12-10T13:46:20.857Z"
}

10. Provide Hypermedia links

The HATEOAS best practice for REST APIs states that the API should not define fixed resource names or hierarchies, as this creates a coupling between the client and server.

Instead, the server should provide instructions to the client on how to construct appropriate URIs through media types and link relations, allowing the server to control its own namespace. This ensures that the resource structure is not determined by out-of-band information and the interaction is driven by hypertext.

Roy Fielding, the designer of the REST principles, states that REST APIs must be hypertext-driven.

Example:

{
  "articles": [
    {
      "id": 1,
      "title": "How to Build a RESTful API",
      "author": "John Doe",
      "date": "2022-01-01",
      "links": [
        {
          "rel": "self",
          "href": "https://api.example.com/articles/1"
        },
        {
          "rel": "author",
          "href": "https://api.example.com/authors/1"
        }
      ]
    },
    {
      "id": 2,
      "title": "Building Scalable APIs",
      "author": "Jane Doe",
      "date": "2022-02-01",
      "links": [
        {
          "rel": "self",
          "href": "https://api.example.com/articles/2"
        },
        {
          "rel": "author",
          "href": "https://api.example.com/authors/5121"
        }
      ]
    }
  ]
}

11. Consider applying a rate limit for API calls

Rate limiting is a technique for limiting the number of API requests that a client can make in a given time period.

The API response will usually include information about the rate limit and the client's current usage, so that the client can adjust its behavior accordingly.

A "429 Too Many Requests" HTTP status code and the "Retry-After" header are commonly used to enforce rate limits on API calls.

• The 429 Too Many Requests error status code indicates that the user has sent too many requests in a given amount of time and the API has temporarily blocked further requests from that user.
• The Retry-After header specifies the amount of time the user must wait before making additional requests.
• The Retry-Remaining header specifies the count of remaining calls in the given time frame.

12. Use query parameters

Query parameters allow you to provide additional information in the URL of an HTTP request to control the response returned by the server.

Use query parameters to: