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.
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.
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.
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.
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
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.
So as a general rule of thumb, we can use all adjectives as query string.
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.
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.
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] 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.
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 use a parent name for the resource. It will help in effective grouping of resources.
This 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 returned 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 really killing the API endpoint, aggregate them to a retiral page with a 301.