Reading:
REST API Naming Best Practices

REST API Naming Best Practices

Metamug
REST API 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.

Using Verbs

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.

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

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.

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

Using Adjectives

OK so not to use verbs, but what about adjectives. Adjectives can be part of the query string. This helps not keeping 2 uris for same resource. Same resource can be used with a filter.

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

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

So as a general rule of thumb, we can use all adjectives as query string.

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

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

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. There is a long debate on Stackoverflow about this

Typically you can find singular names for everything but plural nouns aren't available some times. So sticking to singular names will help you not run out of choices. Avoid using jargon, use commonly used words. Adding special characters

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.

Avoid extensions

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.

https://api.example.com/weather/v1.0/maxtemperature.json

https://api.example.com/weather/v1.0/maxtemperature.xml

Word 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 lower case 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 (lower cased) 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.

Using parent resource

The api URL contains multiple elements. Instead of using word delimiters /api/crm-customers. It is better use a parent name for the resource. It will help in 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.

No Dead API Endpoints

None of the endpoints once published should returned 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 really killing the API endpoint, aggregate them to a retiral page with a 301.

Icon For Arrow-up