Avoid special characters, use lowercase names, and more.
Web developers are no strangers to APIs — especially HTTP methods like GET and POST. When it comes to designing APIs, backend engineers or API engineers are familiar with them as well. That means REST is a term that is familiar. It is said that REST is an architecture and not a standard. It was developed alongside HTTP and is most commonly used over HTTP. HTTP is a standard, whereas REST is an architecture. REST is an architectural style that provides constraints that guide API design.
REST APIs are a powerful tool that is widely used by systems to communicate and exchange information according to the Representational State Transfer (REST) architectural pattern. Be it by websites, mobile applications, or enterprise integrations, they are widely used. REST has much more flexibility compared to the previous generation of web services, namely SOAP.
However, in this article, we are going to talk about REST or RESTful only.
While REST APIs are extremely useful, creating them can be a time-consuming process. 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.
There are basically ten guidelines that you can follow to make your API endpoints better:
- Use nouns.
- Use intuitive, clear names.
- Use lowercase letters.
- Avoid special characters.
- Use forward slash (
/). - Separate words with hyphens.
- Don’t use file extension.
- Use camelCase for parameters.
- Use API versioning.
- Consistency.
They do seem very simple to follow, but they are what can make your endpoints look better. So, let’s get started!
1. Use Nouns
When naming your URIs, it is advised to use nouns instead of verbs or adjectives. HTTP methods are technically verbs, hence GET, POST, DELETE, etc. Also, the names represent the contents of a resource or the resources themselves. Hence, it makes more sense to actually use nouns instead.
The URLs that you have typically encountered have the following “syntax”:
https://api.example.com/[resource]For example:
https://api.example.com/users/abcd-efgh-ijklWell, you get what I mean. Basically, when you look at the URL, you can tell that it is accessing the User resource with a particular ID as per the example. Now, if the URL is as follows:
https://api.example.com/getUsers/abcd-efgh-ijklIt simply looks funny. Also, the browser would tell you that the URL is using the GET method if you inspect, so there is no need to add the action word to your URI. Additionally, you will also specify what HTTP method will be used for the particular API.
The next question is whether to use singular or plural nouns. In general, plural nouns are preferred, as they represent more of something generic in a sense (unless your resource is a singular concept like “admin” or “config”).
You will see a deeper explanation of how these plural nouns make sense in a later point about hierarchy.
2. Use Intuitive, Clear Names
When I think about this, it is more like names that use common sense. Try to position yourself as the consumer. As someone who does not know anything about your services, I would expect to be able to understand the basic use of your API just by reading the API endpoint’s naming. If I would like to fully understand how to use it, then I would read deeper.
So, in that sense, it is important to fulfill the what at first glance. Hence, if you use something weird or unclear (i.e. vague names), your consumers definitely will not be able to understand from the very beginning and you would be in trouble.
Ideally, the name has to be something that represents a whole. In addition, you would like to avoid causing confusion by avoiding abbreviations or shorthand as well. Not only must it be intuitive, but it also must be clear (which usually means just spell out the noun).
For example, when you are given:
GET https://api.example.com/usersYou would be able to understand that by using this API, you would be able to access the User resource and get the Users information. Now, a resource can have a lot of data, so plural nouns make more sense. Also, a direct noun like users is understandable and clear.
Here is another example of an unclear one when trying to get the first name of a user:
GET https://api.example.com/users/1234/fnfn looks weird and not intuitive at all because it can be misinterpreted as “function” if you are as nerdy as me.
So, stick with your common sense and choose intuitive, clear names.
3. Use Lowercase Letters
I don’t really get into arguments with my fellow developers over this point, but it is still good to mention. Based on my experience, everybody I have met always uses lowercase words instead of uppercase. Perhaps we have subconsciously accepted this as a norm due to the websites we visit daily also using lowercase.
Ensure that you use lowercase letters in your API URLs. The RFC 3986 specification for URI standards also denotes that URIs are case-sensitive (except for the scheme and host components of the URL). Given the widespread use of it, avoid any unnecessary confusion due to inconsistent capitalization.
4. Avoid Special Characters
You and I have never seen special characters used in the naming of URLs. I mean, this completely goes against 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.
Also, because URLs can only be sent and received using the ASCII character set, your API URLs should contain only ASCII characters. However, that does not mean you can just use all the characters. Things like %20, which represent the space character, should not be used either. Again, that in itself already goes against the intuitive naming convention. Besides, those characters are typically the encoded versions of unsafe characters like space, brackets, etc. in order to prevent confusion and security issues.
So try to avoid using characters like %20 in your naming, as those have other meanings already.
5. Use Forward Slash
Normal people might not know why the words in a link are separated by forward slashes. As a developer, you should be familiar with the reason: The forward slashes denote the URI hierarchy. APIs are typically structured in a hierarchy.
For example:
GET https://api.example.com/users/1234/first-nameThis example says that it retrieves the first name of the user with the ID 1234. So, the forward slash character represents this hierarchy navigation that becomes more specific as you traverse from left to right in the URI.
Sometimes, I like to add a forward slash at the end of a URL for no reason when accessing one. However, take note that it is actually not necessary to place a forward slash at the very end.
In my opinion, this is also why you should use plural nouns appropriately, as one should be able to tell which part is more generic and which part is more specific by glancing at the URL.
6. Separate Words With Hyphens
When a REST API endpoint has multiple words, it is advisable to separate them with hyphens (-). It typically looks clearer and hence more user-friendly than using underscores (_). These two are often confused and I have personally encountered it before. However, please do not use the camelCase (e.g. firstName), as this looks so weird. It would look better like so:
https://api.example.com/users/1234/first-nameAlso, hyphens are much better for Google Search, as hyphens are recommended by Google itself to make its web crawling job easier, thus creating more consistent results.
7. Avoid File Extensions
The use of file extensions is simply seen as unnecessary in URIs. This is because it can cause some issues for the end-users if you change the file type of the results. Hence, it might add unnecessary complexity that you would like to avoid.
8. Use camelCase for Parameters
When designing an API, sometimes you need an input that is queried directly from the URL or known as a query string. More often than not, when you want to get an entity as the return, it is enough to just take in an ID as the input and then we do some magic data fetching from the database based on the requested ID and return the value.
How is that designed then? Like so:
/users/{userId}If you look at the https://api.example.com/users/1234 link, the 1234 is the userId here.
With the above, the user is able to query a user based on their user ID. Now, for the naming convention, it is advisable to use camelCase instead of others. It is good in the sense that you know it is referring to a parameter instead of the link itself at a glance.
9. Use API Versioning
It is recommended to use versioning when building your APIs, as you never know when the next revision of your APIs will be. Don’t always think that your APIs are the final version and usable forever. There is always a chance that new functionality will be added or some changes will have to be done to your APIs. However, one thing you always want to avoid is breaking your existing working APIs.
Why? Because there is a high chance that your users would already be using those APIs, and if you make changes and push them out, your users will not be happy about it. So, how do you tackle this? By using versioning. Also, when you are using versioning from the very beginning and document it, it indirectly tells the users that there might be changes in the future. It is good to “prepare” your users for any upcoming changes ahead of time.
You can use versioning and move it all the way to the left so that, in a sense, it has the highest scope. The version number should be v1, v2, etc., as users should only care about major changes — thus, major versions only. So it should look something like this:
https://api.example.com/v1/
https://api.example.com/v2/For example:
https://api.example.com/v1/users/1234/orders/2By doing so, if the API is being used by external entities, changing the endpoint will not really affect the existing ones.
Additionally, there are about four more ways of doing versioning:
Versioning in the subdomain
This one puts the version within the URI but makes it associated with the domain, like so:
https://v1.api.domain.com/
https://v2.api.domain.com/This is very similar to the versioning placed at the end. However, this has one the advantage that your API can be hosted on different servers.
Versioning as an additional header
This versioning uses MIME types to include the API version. It looks something like this:
GET https://api.example.com/users/1234 HTTP/1.1
Accept: application/json
Version: 1
GET https://api.example.com/users/1234 HTTP/1.1
Accept: application/json
Version: 2Versioning as an additional field in the accept-/content-type header
This one is similar to the previous point on how to include it, except the result is different. Here is how it looks:
GET https://api.example.com/users/1234 HTTP/1.1
Accept: application/json; version=1
GET https://api.example.com/users/1234 HTTP/1.1
Accept: application/json; version=2Versioning as a media type
This is also similar, as the three previous ways all use the MIME types thing. The only differences are where or how to put the versioning. Here are some examples:
GET https://api.example.com/users/1234 HTTP/1.1
Accept: application/vnd.<host>.users.v1+json
GET https://api.example.com/users/1234 HTTP/1.1
Accept: application/vnd.<host>.users.v2+json10. Consistency
Last but not least, don’t confuse your users by having inconsistency in your APIs. Keep it consistent throughout.
Wrapping Up
With so many suggestions and naming conventions to worry about when building REST APIs, it is no wonder that sometimes it takes a long time to build one. You may even debate with your fellow developers about the naming conventions themselves, which will then incur more time.
Long story short, people do have guidelines that they tend to agree with. Most people should agree with the points above. Hence, I hope by now that you better understand how naming APIs as well as resource hierarchy work.
Just remember that your naming conventions should be:
- Easily understandable.
- Easily linkable.
- Consistent.
In the end, who is more important? They are the consumers. When it comes to naming, just thinking from the consumer’s perspective will help too. As we all know, naming in software development is critical and also very hard at the same time. I hope you found this article helpful.
Thank you for reading!