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.
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/23We have to see Shoes as a singular entity.
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/loadtemperatureAction 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/checkoutLogin, 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.
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/maxtemperatureAdjectives 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=maxSome 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.xmlNot 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.
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/customersThis form of URL provides a hierarchical structure. It helps for better navigation. Also, HATEOAS can be added to link to parent resource URI.
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
In the case when you are killing the API endpoint, aggregate them to a retiral page with a 301.