Master your API: Naming conventions

Naming things is probably the most common thing a developer does.

Naming your API properly is essential to provide clarity and facilitate its usage. Let’s see some best practices for naming REST APIs.

Tips

Define good resources

The resource represents the data or functionality exposed by the API and is typically identified by unique URIs (Uniform Resource Identifiers).

When we are talking about REST API defining good resources is essential to avoid confusing APIs.

❌ /data -> This endpoint can be a little confusing, it is important to define clear resource names.

✅ /products -> Now is much easier to undestand what is the goal of this resource

Note: Having deep knowledge of the domain can help a lot in defining good name for the resources.

Use noun

The resources are described by nouns, you should not use verbs. Using verbs goes against the RESTful architectural style, which emphasizes using HTTP methods to represent actions on resources.

❌ /createUser

✅ /users

Use plural

Use plural for the resource name, this is more aligned with RESTful best practices, as we can have a single resource URI that can return a list or a single element.

❌ /user

✅ /users

Use Hyphens for resources

The name of the resource should follow the name conventional from RFC1738. Using Hyphens improves the readability.

“Scheme names consist of a sequence of characters. The lower case letters "a"--"z", digits, and the characters plus ("+"), period ("."), and hyphen ("-") are allowed…”

RC1738

To make your URIs easy for people to scan and interpret, use the hyphen (-) character to improve the readability of names in long path segments. Anywhere you would use a space or hyphen in English, you should use a hyphen in a URI

REST API Design Rulebook - Mark Masse's

❌ /users/profileSettings

✅ /users/profile-settings

Keep a standard for query parameters

If your API has pagination or a common standard for filter, apply the same query parameter for all endpoints that make sense to have it. This makes your API easier to use and understand.

❌ /users?size=3&page_numer=0
   /products?limit=3&offset=0

✅ /users?page=2&limit=10
   /products?page=0&limit=10

Many guidelines recommend using hyphens for query parameters, while others suggest using camel case. The most important thing is to follow a convention and ensure that this standard is maintained throughout your entire API.

❌ /users/{user_id}
   /products/{productId}

✅ /users/{userId}
   /products/{productId}

Hierarchical URI Structure

Using Hierarchical URI is essential to provide a clean REST API, but it should be used properly to avoid complex hierarchy resources.

❌ /products-categories

✅ /products/categories

In case you have a complex hierarchy, with a long chain of nested resources, it can become a problem to use and maintain. In this case, separating the resources can be a better approach.

❌/products/{productId}/categories/{categoryid}/reviews/{reviewId}/comments

✅ /reviews/{reviewId}/comments?productId=?&categoryId=?

Conclusion

We’ve seen many good practices related to naming conventional for REST API.

By following these practices, you guarantee an API easier to use as it is more readable and follows the market standard. Not only that, but your API will also be easier to maintain and involve.

I hope these tips have been useful to you, and if you know any other tips related to conventional nomenclature, share them here.

References

Azure Naming Guidelines

Swagger - Best Practices in API Design

Zalando - RESTful API and Event Guidelines

REST API Design Rulebook - Mark Masse's