REST URL naming conventions

Photo by Remotar Jobs on Unsplash

There are many reasons to name api endpoints thoughtfully. Choosing sensible names for API endpoints can drastically smooth out the learning curve for new developers and helping them intuitively know what to look for and where to find it. In this article we will go through most effective best practices and conventions for naming API endpoints.

REST is an architecture and not a standard. REST means REpresentational State Transfer. It was developed alongside HTTP and is most commonly used over HTTP. HTTP is a standard but REST is an architecture. REST APIs are widely used by many organizations to successfully manage information about their resources. REST has much more flexibility compared to the previous generation of web services, namely SOAP.

REST APIs are very useful, but creating them is very time-consuming task. If you are building your own REST or RESTful API, you should know that there are best practices to follow. This includes the naming of your REST API endpoints. Because it will increase the readability of your api and developers can easily understand the flow of the website.

There are some conventions followed when naming a URL.
1. Use nouns
2. Pluralized resources
3. Forward slashes for hierarchy
4. Punctuation for lists
5. Query parameters where necessary
6. Lowercase letters and dashes
7. Do not use file extensions
8. Avoid Special Characters

Use nouns
When naming your URIs, it is advised to use nouns instead of verbs or adjectives. RESTful URLs should not indicate any kind of CRUD (Create, Read, Update, Delete) functionality. But REST APIs should allow you to manipulate a resource which should take the form of noun through on the main HTTP methods.

Pluralized resources
Next one is the question of whether resource name should be pluralized. Admittedly, this is a matter of preference; however, most API design experts would suggest you pluralize all resources unless they are singleton resources.

Forward slashes for hierarchy
Forward slashes is used to indicate the hierarchy of resources and collections. Developers can easily understand about api functionality and flow.

Punctuation for lists
If there is no hierarchical relationship, punctuation marks such as semicolon or comma should be used.

Query parameters where necessary
In order to sort or filter a collection, a REST API should allow query parameters to be passed in the URI.

Lowercase letters and dashes
By convention, resources names should use exclusively lowercase letters. similarly, dashes (-) are conventionally used in place of underscores(_).

Avoid file extensions
The use of file extension is simply seen as unwanted in URIs. Because it can cause some issues for the end-users if you change the file type of the results.

Avoid Special Characters
Very rare to see using special characters in URLs. This violate the intuitive, clear naming guideline that we talked about earlier. Imagine that you introduce these special characters into your naming. It will be confusing for the users and technically complex. They are just unnecessary.

I hope in this article you can understand about REST URL naming conventions. Thanks for reading.

References

https://restfulapi.net/resource-naming/

https://nordicapis.com/10-best-practices-for-naming-api-endpoints/

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store