REST API Guidelines at Feedzai

Bread and butter (by Whitney Wright)

REST APIs are the bread and butter of web (and other types of) applications.

However, as a product and its team grows, it’s easy for once well-known conventions to be lost and for inconsistency to creep in. This is why guidelines are a key tool in communicating conventions and best practices.

When writing our guidelines, we not only looked at our existing conventions but also researched what were the best practices used by other companies. This was helpful to validate our assumptions and, as we now wanted to share our opinionated set of guidelines, in helping others’ research.

Naming

• Use camelCase — camelCase has the advantage that it can also be used as variable names and is more easily readable than lowercase.
• Write resource names in plural (e.g., plans).

Examples of what to do 👍

• GET /api/users/:id/deletedRepositories/:id
• GET /api/blogs/:id/visitorStatistics

Examples of what not to do 👎

• GET /api/users/:id/deletedrepositories/:id
• GET /api/blogs/:id/visitor_statistics

Use Simple Nouns and Avoid Verbs

• Use simple nouns and avoid long chains of words.
• Avoid verbs and instead use the semantics of the HTTP methods.

Examples of what to do 👍

• GET /api/users
• POST /api/blogs/:id/drafts

Examples of what not to do 👎

• GET /api/users/:id/repository/:id/repositoryAbreviatedHistoryListPaged
• POST /api/blogs/createDraft

Think of the REST API, not only the Back-End API

The REST API is an interface that will be used by many developers in order to exchange data and trigger actions. So, a well structured and designed REST API will make the developer life much better by providing a smooth developer experience. Because if you have a confusing and unusable, the REST API developers will starting to look for alternatives and stop to use it.

The most perpetual battle in REST APIs is related to the developer experience (and this battle usually is taken between Back-end and Front-end Developers). So in order to mitigate this, don’t forget to describe the changes made into the API as early as possible and iterate those changes with the developers that use your REST endpoints services. If that is not possible, please include a developer that uses the API extensively (for example, a Front-End developer) in the code reviews and provide a meaningful description of the changes.

Respect the Semantic of the HTTP Methods

For more details, have a look at this article.

Return Codes

Please follow these guidelines regarding error codes:

2xx codes should be used for successful operations

• 200 for successful requests that have a response
• 204 for successful requests that do not have a response

3xx codes should be used for redirects

4xx codes should be used for handled errors

• 400 for requests that contain errors such as validation errors or invalid input errors
• 401 for requests that are not authorised
• 403 for requests that are trying to access a resource for which they do not have permissions (but that they can know it exists)
• 404 for requests that contain an id that points to a resource that no longer exist (and for similar errors)

5xx codes should be used for unhandled errors

• 500 for unhandled errors (sent only by a catch all handler)

Note that resources that the user is not authorised to see are like resources that do not exist and, as such, for those resources we should return a 404.

Always Use JSON

Always use JSON for the received and sent payloads. Avoid sending raw strings that are not JSON-encoded and do not expect requests to send information form encoded.

Also, use the naming guidelines described in this document in the JSON properties (e.g., use camelCase, simple names, etc).

Keep Relevant Stakeholders in the Loop

Validate API changes and new APIs with Front-End developers and/or other products/clients that may be using the API. Front-end developers are the main users of the REST API and they can often provide valuable feedback regarding consistency, ease of use, etc.

Documentation

Always document endpoints (for example, using swagger).

Returning Errors

Errors should be returned using error codes and using the JSON object described below:

[{
    error: <ERROR_CODE>,
    parameters: [<STRING>]
}, {
    ...
}, {
    ...
}]

This format allows to send one or more errors and it delegates the job of building the message itself to the Front-End. In JSON, we will send an error code identifying the error and several parameters that will give additional information about the error.

For example the following JSON:

[{
    error: 12,
    parameters: ["gs62hhsdd"]
}]

Would be transformed, by the Front-End, in the following user-facing message: “An error occurred while saving your article. If this problem persists, contact support and provide the following id gs62hhsdd.“

Error codes should be stored in an enum that is either shared with the Front-End code or duplicated there.

Wrapping Up

Please note that these guidelines won’t make sense to every project, as they are not perfect guidelines. These are one possible set of guidelines (out of many) that have been working for us. More important than what these specific guidelines are is to be consistent when following them. But remember, at the end of the day it is all about giving the best developer experience because a good structured and well-written API reduces the friction during the product integrations and enables a good usage of the product by itself.