Best Practices for Naming REST API Endpoints
When building a REST API, one of the key decisions you will be making is - “How to name your resources and endpoints.”
The names you choose will have a significant impact on the usability, maintainability, and overall success of your API.
In this post, we will discuss some of the best practices for naming resources and endpoints in a REST API.
Table of Contents
- What is REST API?
- What are REST API Endpoints?
- REST API End Points Naming Best Practices
- Conclusion
What is REST API?
An API (Application Programming Interface) is a bunch of rules that define how applications connect with one another. A REST API is a type of API that adheres to the design principles of REST.
REST, or Representational State Transfer, is a popular architectural style that is used for building web services. It has been crafted based on a set of certain principles that clearly define how resources should be represented and interacted with over the internet.
Some of the key principles of REST are -
- Every resource must be identified by a Uniform Resource Identifier)
- Every interaction between the client and the server should be made via a set of standard HTTP methods. For example - GET, POST, PUT and DELETE.
- Every resource must be self-describing. It should have a clear representation format like JSON or XML.
- Every resource must be stateless. In other words, every request should contain all the information needed to complete that request.
What are REST API Endpoints?
REST API Endpoints are typically URLs that you can use to send requests to a RESTful API. In other words, they define the location of a particular resource along with the supported actions that can be performed on it.
REST API endpoints are generally defined through standard HTTP methods, such as:
- GET: Retrieve a resource
- POST: Create a resource
- PUT: Update a resource
- DELETE: Delete a resource
Example:
https://api.example.com/users could be an endpoint to get all users.
https://api.example.com/users/{id} could be an endpoint to retrieve a specific user by id.
As you can see, each endpoint corresponds to a particular resource. You would have also noticed that the endpoint's URL includes variables that indicate the specific resource.
In this next section, we will discuss some of the best practices you must employ while naming endpoints in a REST API.
REST API End Points Naming Best Practices
Here are some handy tips to name your REST API endpoints -
Use clear names
You might wonder what exactly we mean by clear. To understand this better, all you have to do is put yourself in the end user’s shoes. You need to answer yourself - does this name explain the basic use of my API? If it doesn’t, make the name clear and descriptive.
Weird or vague names will not be easily comprehensible, even for the most educated audience. For instance, you must avoid abbreviations and short forms unless they are very popular globally. Use nouns & avoid verbs There is a simple reason - HTTP methods are usually verbs. This explains why GET, POST, DELETE, etc., are named so. Endpoints, on the other hand, should clearly indicate the resource or resources they are associated with. So you must use nouns that accurately describe the resource, for example, "users" or "items.”
https://api.example.com/users/abc
makes more sense than
https://api.example.com/getUsers/abc
Why?
Because when you inspect, the browser will automatically tell you that the URL is using the GET method. There is no point in unnecessarily adding an additional verb to the URI.
Also, make it a point to use a plural noun when representing a collection of resources. For example, use "users" to represent a collection of users. In fact, we would recommend always using a plural noun unless the resource represents something singular, like ‘admin.’
Use lowercase characters
Except for the scheme and host components of the URL, URIs are generally case-sensitive. This makes it very important to use the right case while naming the resources. The general rule is to always use lowercase characters because -
- It is a widely accepted convention in the industry and helps to maintain consistency across different APIs.
- Lowercase letters are generally easier to read than uppercase letters, especially when in long names or URLs.
- Lowercase letters are more common in URLs and are used by search engines to index web pages. So, by using lowercase letters in your endpoints, you can help improve the discoverability of the API in search engines.
Avoid special characters
It’s common knowledge that URLs can be sent and received only using the ASCII character set. That doesn’t mean you can go ahead and use every character on the set to name your resources. It will go against the intuitive naming convention followed while naming API resources. Many of the characters will have other meanings already and will result in unwanted confusion and security issues.
Besides the above reasons, some systems and programming languages might not have the capability to handle special characters correctly. This will result in issues with your API. Avoiding special characters will ensure that your API is compatible with a wide range of technologies.
In case you want to separate words in endpoint names, you can use hyphens.
Conclusion
By following the best practices highlighted in this post, you can ensure that your API is clear, consistent, and easy to use, which will ultimately lead to greater adoption and success of your API.