REST URL Naming Conventions
All the restful web services have an URL to access them. Someone has to name those URLs. So there are best practices for REST URL Naming. In this article lets discuss about the best practices of REST URL Naming.
The URLs map to their respective endpoint handler. Depending on the framework used these URLs are defined in the code or configuration.
The RESTful endpoint of a URL consists of application context, version, resource and parameter.
REST APIs use Uniform Resource Identifiers (URIs) to address resources.
There are some tips for naming REST API endpoints.
- Use nouns for naming URIs
URIs should be named with nouns that specify the contents of the resource, rather than adding a verb for the function that is being performed.
Eg: You should use https://api.example.com/users instead of https://api.example.com/getUsers.
This is because CRUD (create, read, update, delete) functionality should already be specified in the HTTP request (e.g. HTTP GET https://api.example.com/users).
Use plural nouns is preferred unless the resource is clearly a singular concept (e.g. https://api.example.com/users/admin for the administrative user).
2. Use intuitive, clear, unabridged names
You should use URI names that are intuitive and clear, something that third parties could guess even if they’ve never used your API before. In particular, avoid abbreviations and shorthand (e.g. https://api.example.com/users/123/fn instead of https://api.example.com/users/123/first-name)—unless that abbreviation is the preferred or most popular term, in which case feel free to use it (e.g. https://api.example.com/users/ids instead of https://api.example.com/users/identification-numbers).
3. Use forward slashes to denote URI hierarchy
The forward-slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources.
Eg: https://api.example.com/users/123/first-name will retrieve the first name of the user with ID number 123.
The forward slash (“/”) character should be used to navigate this hierarchy, moving from general to specific when going from left to right in the URI.
But it’s not necessary at the very end of the URL, where they add complexity without adding clarity.( Eg: you should use https://api.example.com/users instead of https://api.example.com/users/.)
4. Separate words with hyphens
When a REST API endpoint contains multiple words (e.g. https://api.example.com/users/123/first-name), you should separate the words using hyphens. This is typically clearer and more user-friendly than using underscores (e.g. first_name) or camel case (e.g. firstName), which is discouraged due to its use of capital letters.
5. Use lowercase letters
Should use lowercase letters in API URLs because URIs are case-sensitive. Lowercase letters for URIs are in widespread use, and also help avoid confusion about inconsistent capitalization.
6. Avoid special characters
Special characters are not only unnecessary, they can also be confusing for users and technically complex. Because URLs can only be sent and received using the ASCII character set, all of your API URLs should contain only ASCII characters.
7. Avoid file extensions
While the result of an API call may be a particular filetype, file extensions are largely seen as unnecessary in URIs, they add length and complexity.
Eg: You should use https://api.example.com/users instead of https://api.example.com/users.xml.
In fact, using a file extension can create issues for end users if you change the filetype of the results later on.
References: