URL Naming Conventions in Web APIs

If you’re building your own REST API, you should be familiar with some of the industry best practices for naming REST API endpoints.

It is very important to know the best practices for naming your RESTful APIs. Using the REST API naming conventions dramatically reduces the learning curve and makes it easier for new developers and third-party users to get started with the API. The more people who understand how to use the proper methods, the easier it will be for everyone. These standards should be required for every URI naming process.

What is the URL?

A URL is a specific type of URI that includes the location of a resource and the protocol used to access it.

It can be divided into several parts:

scheme:// authority path ? query # fragment

1. Scheme : The scheme is the first part of the URL and indicates the protocol used to access the resource. Common examples include “http”, “https”, “ftp”, “file”, and “data”.
2. Authority : The authority is the part of the URI that identifies the specific resource. It typically includes the domain name or IP address of the server hosting the resource and the port number used to access it. For example, in the URI http://www.example.com, the authority is www.example.com.
   1. Host : The host is the domain name or IP address of the server hosting the resource. It usually comes after the schema and is separated by “://” (double slashes). For example, in the URL http://www.example.com, the host is www.example.com.
   2. Port : The port is the number used to access the resource on the server. It is optional and comes after the host separated by “:” (colon). For example, in the URL http://www.example.com:8080, the port is “8080”.
3. Path : The path is the part of the URL that follows the host and port and is used to identify the specific location of the resource on the server. You can include forward slashes “/” to indicate subdirectories. For example, in the URL http://www.example.com/about, the path is “/about”.
4. Query : The query is the part of the URL that comes after the route and is used to send additional information to the server. It is usually separated from the path by a question mark “?”. For example, in the URL http://www.example.com/buscar?q=example, the query is “q=example”.
5. Fragment : The fragment is the last part of the URL and is used to identify a specific section of the resource. It is separated from the rest of the URL by a “#” symbol. For example, in the URL http://www.example.com/about#history, the snippet is “history”.

It is important to note that not all URLs include all of these parts. Some URLs may only include a scheme, a host, and a path, while others may include all of the above.

URL Naming Conventions in REST APIs

When designing URLs for a REST API, it is good practice to follow these naming conventions:

• Use nouns to name URIs : Use nouns to represent resources instead of verbs.

http://www.example.com/users //yes
http://www.example.com/getUsers //no

• Use plural and singular: Use plural names for collections of resources and singular names for individual resources.

http://www.example.com/users //collection
http://www.example.com/user //user specific.

• Use forward slashes to indicate URI hierarchy: Use a forward slash “/” to separate the different levels of the resource hierarchy.

http://www.example.com/users/{idUser}/orders //to indicate that orders belong to a specific user

• Separate words with hyphens and lowercase: Use lowercase letters and hyphens to separate words.

http://www.example.com/users/{idUser}/pending-orders //yes
http://www.example.com/users/{idUser}/OrdersPending //no

• Use route parameters: Use route parameters to identify specific resources.

http://www.example.com/users/{idUser} //to identify a specific user.

• Use query parameters: Use query parameters to filter or sort resources.

http://www.example.com/users?name=peter&order=asc

• Use HTTP verbs to indicate the action to perform on a resource . For example, use GET to retrieve a resource, POST to create one, PUT to update it, and DELETE to delete it.
• Avoid file extensions .

http://www.example.com/users.xml //no
http://www.example.com/users //yes

Conclusion

It’s important to keep URLs simple and consistent so they’re easy to understand, remember, and use. In addition, it is recommended that you follow existing industry conventions to ensure compatibility and interoperability with other systems.