3 Endpoint Naming

Overview

The RESTful API Endpoint Naming Standards are a set of guidelines we follow to maintain consistency, clarity, and usability in our APIs.

Application Programming Interfaces (APIs) act as the gateways to data and capabilities of our applications. With the REST architectural style, we can create scalable APIs that are easy to consume and understand.

Following a set of established naming conventions helps us create APIs that are straightforward to use, which in turn accelerates development, minimizes the risk of errors, and makes our services easier to consume.

Tip

Although these are presented as standards, they should be considered as guidelines. In specific cases, there might be valid reasons to deviate from these standards. However, any deviation should be carefully considered and thoroughly discussed within the team.

3.1 Endpoint Naming Principles

3.1.1. Resource Identification

RESTful APIs use nouns (not verbs) to identify resources or collections of resources. For example, use /users not /getUsers or /createUser.
3.1.2 Consistency

Maintain consistent naming conventions across the API. This reduces ambiguity and increases usability.
3.1.3 Plural Form Resources

Resources should be named in plural form, such as /users rather than /user.
3.1.4 Hierarchical Relationships

Use sub-resources to show relationships between resources. For example, to get a user's comments, you can use /users/{id}/comments.
3.1.5 Lowercase Letters

Use lowercase letters for resources and collections. Mixed case or camelCase can lead to confusion and errors.
3.1.6 Avoid Underscores (_)

Underscores can sometimes be interpreted as spaces in certain contexts and should be avoided. Use hyphens (-) for better readability if needed².
3.1.7 No Trailing Slashes

Trailing slashes should be avoided. For example, use /users not /users/¹.
3.1.8 Non-CRUD Functions

For routes that don't easily map to CRUD operations (Create, Read, Update, Delete), consider mapping these to HTTP methods in a sensible way, or group them under a sub-resource. For example, /users/{id}/activate.
3.1.9 Filters, Sorting, and Pagination

For large collections, these should be expressed as query parameters. For example, /users?status=active&sort=-registered&page=2.
3.1.1 HTTP Status Codes

Use appropriate HTTP status codes to indicate the status of the request. For example, '200' for successful GET requests, '201' for successful POST requests, '400' for bad requests, etc.

HTTP Status Codes

For more information on the correct status codes to use, see the response status codes section of the HTTP Standards page.
3.1.1 Error Handling

Always return meaningful error messages and codes, helping the consumer understand what went wrong and how they might fix it.

Warning

Remember that these are guidelines, not hard rules. They serve as a starting point for the API design, but each API has unique needs and may require certain exceptions or adaptations. Always prioritize clarity, simplicity, and usability when designing your API.

3.2 When Exceptions are Required

Despite these guiding principles, there may be situations that require exceptions or deviations. These could include compatibility with legacy systems, specific requirements of certain clients, or other unique constraints.

In such cases, exceptions should be carefully considered, thoroughly discussed within the team, and clearly documented to avoid confusion and ensure everyone understands the reasons behind the deviation.

Always consider the potential impact of any exceptions on the overall usability, clarity, and consistency of the API, and strive to minimize such deviations as much as possible.