Master your API: Naming conventions
Published: 2024-07-01 19:08:56


![Master your API](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fmyc1hi5bsby8d0uyqyo.png)

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](https://www.ietf.org/rfc/rfc1738.txt). 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](https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md#common-names)

[Swagger - Best Practices in API Design](https://swagger.io/resources/articles/best-practices-in-api-design/)

[Zalando - RESTful API and Event Guidelines](https://opensource.zalando.com/restful-api-guidelines/#118)

REST API Design Rulebook - Mark Masse's