Reading:
Top 6 REST Naming Best Practices

Top 6 REST Naming Best Practices

Metamug
Top 6 REST Naming Best Practices

All restful web services have an URL to access them. Someone has to name those URLs. The URLs map to their respective endpoint handler. Depending on the framework used these URLs are defined in the code or configuration.

https://api.example.com/weather/v1.0/temperature

In the above example, you can see, most parts of the URL will be consistent. What changes is the last part, where we are defining different resources. These resource paths form the URL (Uniform Resource Locator).

So the hard part here is to first come up with the name of the resource in the URL that specifies the purpose of the API resource. It should be understood by others using the API

There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton

What is the purpose of a URL?

If pointing to an address is the answer, then a shortened URL is also doing a good job. If we don't make it easy to read and maintain, it won't help developers and maintainers alike. They represent an entity on the server, so they must be named logically.

1. Using commonly used nouns as resource names

Use commonly used nouns to name resources. Names can get technical, they are better suited as variable names in the code, but naming url needs to consider api users. Choose names that can be easily understood in the domain of the api. Avoid ambigious names, as the api users will not refer to the docs often and can easily make mistakes sending requests.

Coming up with the correct noun is important for the resource in the picture. Then we must decide if the resource can be singular or plural. Whatever you choose, be consistent with the choice. Typically you can find singular names for everything but plural nouns aren't available sometimes. So sticking to singular names will help you not run out of choices. Avoid using jargon, use commonly used words.

For things without singular names

In the case of trousers and sunglasses, they don't seem to have a singular counterpart. They are commonly known and they appear to be singular by use. Like a pair of shoes. Think about naming the class file Shoe or Shoes. Here these names must be considered as a singular entity by their use. You don't see anyone buying a single shoe to have the URL as

/shoe/23

We have to see Shoes as a singular entity.

2. Use Action Verbs with Resource Nouns

In the above example, we used temperature to access temperature information. Using verbs in the URL like "getting", "fetch", "find", "load" are a bad idea since HTTP has methods to do that for us.

# Do not use these resource names
https://api.example.com/weather/v1.0/gettemperature
https://api.example.com/weather/v1.0/fetchtemperature
https://api.example.com/weather/v1.0/loadtemperature

Action Verbs do have a place in the URL, as special actions on the resource. The resource can have actions specific to itself unlike "get", fetch, load. Do not introduce action verbs when they are not necessary.

# Correct Resource Names in url
http://api.example.com/weather/v1.0/user/login
http://api.example.com/weather/v1.0/user/logout
http://api.example.com/weather/v1.0/user/checkout

Login, logout, checkout, etc. are actions specific to the user. They can be used on the temperature resource. So they belong in the URI. Here is an example. The action should always be followed by the resource in the URL. This is to specify the association between the action and the resource.

3. Adjectives as Query String

OK, so not to use verbs, but what about adjectives?

# Incorrect use of adjectives
https://api.example.com/weather/v1.0/latesttemperature
https://api.example.com/weather/v1.0/maxtemperature

Adjectives can be part of the query string. Query strings help us handle different requests on the same URL. The query string is can be seen as a filter on the resource. So as a general rule of thumb, we can use all adjectives as a query string.

https://api.example.com/weather/v1.0/temperature?filter=latest
https://api.example.com/weather/v1.0/temperature?filter=max

4. Avoid extensions and special characters

Some of the popular frameworks add extensions to the URL. Moving the framework may affect the endpoint. Also, avoid extensions to display response content type. The below example we have to support another response format we have to add another url, for e.g. .yml.

# Avoid extensions
https://api.example.com/weather/v1.0/temperature.do
https://api.example.com/weather/v1.0/temperature.json
https://api.example.com/weather/v1.0/temperature.xml

Not just at the end of the url, avoid extensions anywhere in the url.

Special characters are not welcomed in naming any API endpoint. Since the will be URL encoded. They must be readable.

The name of the resource in the endpoint must use logical domain-specific nouns. Nouns do not have special characters. You don't get to hear something's name with a hash(#) or a pound(!) in it.

5. Hyphen and Resource Nesting as delimiters

Naming an API resource may be a combination of 2 or three words. In such a case it can be confusing to read the endpoint. Remember the API endpoint and its response is the GUI. As API developers we should ensure we use a consistent delimiter to make the resource name readable.

I have not been in favor camel case since it asks you to have capital letters in the URL. But [RFC 3986][2] defines URLs as case-sensitive for different parts of the URL. Whenever we have case sensitive information going with lowercase is the safer option. Coming from a programming background, camelCase is a popular choice for naming joint words. Since URLs are case sensitive, keeping it low-key (lowercased) is always safe and considered a good standard. Now that takes a camelCase out of the window.

Google recommends keeping all the keywords in the URL separated by a hyphen.

Consider using punctuation in your URLs. The URL http://www.example.com/green-dress.html is much more useful to us than http://www.example.com/greendress.html. We recommend that you use hyphens (-) instead of underscores (_) in your URLs.

But try to avoid the word delimiter when you can do without it.

The API URL contains multiple elements. Instead of using word delimiters /api/crm-customers. It is better to use a parent name for the resource. It will help in the effective grouping of resources.

/api/crm/customers

This form of URL provides a hierarchical structure. It helps for better navigation. Also, HATEOAS can be added to link to parent resource URI.

6. No Dead API Endpoints

None of the endpoints once published should return 404. They must always redirect with a 302 or 301 or 307 to another endpoint. We may have to do this when

  • The business requirement changes the noun used.
  • The API is merged with another one

In the case when you are killing the API endpoint, aggregate them to a retiral page with a 301.

Icon For Arrow-up