Terence Bennett - December 5, 2023
REST APIs are a powerful tool to bring together multiple applications. While REST APIs are extremely useful, creating and deploying them into production is a highly complex and time-consuming process. If you’re building your own REST API, you should be familiar with some of the industry best practices for naming REST API endpoints. For many developers, using a development platform is a good way to get started. It streamlines the development process and ensures you’re able to get started immediately.
Here are the our recommended naming conventions to follow for REST API endpoints:
- REST API endpoints should follow good naming practices for better usability, maintainability, and scalability.
- Use nouns, preferably plural, to represent resources, aligning with the REST architectural style.
- Avoid deep nesting and unnecessary special characters in endpoint names.
- Separate words with hyphens and use lowercase letters to prevent confusion.
- Don’t use file extensions in URIs. Use the Content-Type entity-header to denote the original file type.
- Consistent naming conventions in REST API endpoints enhance readability, understanding, and troubleshooting, and foster growth and scalability.
Table of Contents
What are REST API Endpoints?
REST API endpoints are the cornerstones of communication in web services, serving as interaction points where specific URLs are configured to receive web requests. They allow different software applications to talk to each other by defining the methods and data formats they can use. Each endpoint is a specific URL where an API can access the resources they need, such as server data, and perform operations using standard HTTP methods, including GET, POST, PUT, and DELETE. Naming these endpoints appropriately is crucial for readability, maintainability, and ease of integration, thereby ensuring a seamless user experience.
Here’s a quick guide to help you understand the best API endpoint naming conventions!
API Endpoint Naming Best Practices
Navigating the digital labyrinth of APIs becomes significantly easier when there’s a clear, well-established path to follow. This is the essence of employing best practices when naming REST API endpoints. REST, or Representational State Transfer, provides a set of architectural constraints that enhance the performance, scalability, and modifiability of web services. Naming conventions, an integral part of these constraints, offer a systematic way to structure API endpoints, making them predictable and easily understandable. Although it might seem like a minor detail, the way we name our endpoints can have a profound impact on the user experience, maintainability, and overall success of an API.
Use Nouns to Name URIs
All REST APIs have a URL at which they can be accessed, e.g. https://api.example.com. Subdirectories of this URL denote different API resources, which are accessed using a Uniform Resource Identifier (URI). This is an easy way for developers to ensure the name makes sense and can be understood by anyone. For example, the URI https://api.example.com/users will return a list containing the users of a particular service. The web APIs make it easier to understand which web services are in use.
In general, URIs should be named with nouns that specify the contents of the resource, rather than adding a verb for the function being performed. For example, 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). There is no need to repeat the information, which keeps the URI easy to read while showing that it is the Get Method needed. A content-type header can be a good way to name the URI. In rare cases, you can use HTTP verbs, but it’s best to stick to nouns for the rest endpoint name.
Should I Name Rest APIs Plural or Singular?
Using nouns for naming URIs is a REST API naming best practice, but you may wonder if plural or singular nouns are best. When should you use singular or plural nouns? In general, you should name your URIs with plural nouns. The exception to this is when you have a concept that is obviously singular, which rarely happens. (e.g.https://api.example.com/users/admin for the administrative user).
Use Clear, Unabridged Names That Are Intuitive
When naming REST API endpoints, you should use URI names that are intuitive and easy to understand. Consider the person checking the URI when they’ve never used your API previously. They should be able to easily guess what words are used and how they are structured. You should definitely avoid abbreviations and shorthand (e.g. https://api.example.com/users/123/fn instead of https://api.example.com/users/123/first-name). In some cases, the accepted or popular term for something is the abbreviation, which means you can use it. (e.g. https://api.example.com/users/ids instead of https://api.example.com/users/identification-numbers). Remember to keep it simplistic enough that anyone new to your API can simply guess the URI. If everyone uses the same methods to name their REST API endpoints, it makes it easier to work with them.
You are naming the resource, which may be a singleton or a collection. As soon as an end user sees the name, they’ll know exactly what it is. For example, you may use “customer” or “users” as your resource name. Subcollections also need to be defined. This ends up looking something like “/users/client-id/accounts/account-id.” As you can see, it clearly shows the hierarchy of the URI, which makes it possible to trace the resource even if someone is unfamiliar with your API.
Creating REST APIs can be confusing if you don’t have the necessary information. Aside from learning how to name the API, do you know how to create it? Take a look at DreamFactory’s solution with our free 14-day hosted trial.
Use Forward Slashes to Denote URI Hierarchy
REST APIs are typically structured in a hierarchy. For example, https://api.example.com/users/123/first-name will retrieve the user’s first name with ID number 123. The forward slash (“/”) character should be used to navigate this hierarchy and to indicate where you are. It moves from general to specific when going from left to right in the URI.
While forward slashes are suitable for denoting the hierarchy of your API, they’re not necessary at the very end of the URL. Adding this extraneous slash increases complexity without adding clarity. For example, you should use https://api.example.com/users instead of https://api.example.com/users/.
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 with hyphens. It’s a good way to make the URI easier to read and is a universal method that everyone can understand.
It’s generally accepted that a hyphen is 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 (see below). The hyphen is easy to type, and with all developers on the same page, it can streamline the URIs to ensure everyone has access.
Use Lowercase Letters
Whenever possible, use lowercase letters in your API URLs. This is mainly because the RFC 3986 specification for URI standards denotes that URIs are case-sensitive (except for the scheme and host components of the URL). Lowercase letters for URIs are in widespread use, and also help avoid confusion about inconsistent capitalization. If you add capital letters, you should be aware that this will cause confusion and result in user error more often than not.
Avoid Special Characters
Special characters are not only unnecessary, they may confuse users who are familiar with API design and naming. They aren’t available to everyone easily and are 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.
In addition, try to avoid the use of “unsafe” ASCII characters, which are typically encoded in order to prevent confusion and security issues (e.g. “%20” for the space character). “Unsafe” ASCII characters for URLs include the space character (“ “), as well as brackets (“[]”), angle brackets (“<>”), braces (“{}”), and pipes (“|”). Keep your names as simple as possible and you shouldn’t have any problems. In most cases, these are the same as HTTP methods.
Avoid File Extensions
While the result of an API call may be a particular filetype, file extensions such as .HTML are largely seen as unnecessary in URIs, as they add length and complexity. For example, 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. You don’t need to use node.js or similar, for example. It can be simplified.
File extensions in URIs will often create confusion and also make it harder to intuit the URI if it is unknown. File extensions do not need to be included and there are other ways to indicate the file type. These should not be included in the REST API design and names.
If you want to specify the file type of the results, you can use the Content-Type entity-header instead. This lets the user know which media type was used for the original resource. It is not always necessary, but if you wish to maintain records of the original file type, you can use this method.
Be Consistent with Naming REST API Endpoints
Choose a system for naming your API endpoints and stick with it. You should document your methods so everyone working with you knows the naming protocols. When you are consistent in your names, this ensures a uniform system across the board. Everyone working with the APIs will find it easy to use them. If they’re unsure of a specific URI, they can assume what it will be, based on the naming protocols.
Maintain records of everything. While there are some generally understood guidelines across the board, you may want to formalize the process. When someone new joins your team, they can quickly access the URI naming protocols and follow them to ensure consistency.
Common Mistakes to Avoid When Naming REST API Endpoints
The clarity and success of your REST APIs heavily rely on how you name your endpoints. While there are recommended practices to follow, it’s equally crucial to understand and avoid common naming errors. Here are some of the frequent missteps.
Using Non-Descriptive Endpoint Names
REST API endpoints should clearly identify a specific resource. If your endpoint names are ambiguous or non-descriptive, they can bewilder developers and users. Stick to simple, intuitive names that clearly reflect the associated resource. Avoid cryptic abbreviations, acronyms, or industry jargon that might not be familiar to all users.
Mixing Case Styles
URIs are case-sensitive as specified by RFC 3986. Mixing upper and lower case letters in your API URLs can lead to misunderstandings and potential errors. Always use lowercase letters in your endpoint names to promote consistency and circumvent potential issues.
Including Verbs in Endpoint Names
A cornerstone of REST architecture is manipulating resources (nouns) using HTTP methods (verbs). Therefore, incorporating verbs in your endpoint names is a poor practice, as the HTTP request method should already specify the performed function. Including verbs in your endpoint names can lead to redundancy and confusion.
Failing to Properly Version Your API
API versioning is crucial for maintaining backward compatibility as your APIs evolve. Failing to include versioning in your endpoint can lead to breaking changes that impact users. Always include the version in your endpoint (e.g., ‘v1’) to ensure smooth transitions as your API evolves.
Benefits of Good API Naming Practices
Establishing an effective, clear, and consistent naming convention for your API endpoints can greatly enhance the usability, maintainability, and scalability of your application. Let’s delve into the benefits of properly naming REST API endpoints.
1. Enhanced Readability and Understanding
A well-named API endpoint immediately tells you what to expect from it, improving readability and understanding. For instance, a GET request to /users intuitively implies fetching a list of users. This clarity simplifies the learning curve for new developers and enhances collaboration among teams.
2. Improved Consistency
Consistent naming conventions make your API predictable and easier to use. Developers can anticipate the structure of the endpoints, leading to fewer errors and quicker API integration.
3. Easier Troubleshooting
If an issue arises, well-named endpoints can expedite the troubleshooting process. When the endpoint reflects its function, it’s easier to locate and correct problems, enhancing productivity and reducing downtime.
4. Facilitates Growth and Scalability
As your application grows, so will the number of your API endpoints. A robust naming convention helps manage this growth effectively, ensuring new endpoints integrate smoothly with existing ones, thereby facilitating scalability.
5. Better User Experience
For clients of your API, clear and intuitive endpoints mean a smoother, more enjoyable experience. A developer using your API will appreciate the thoughtfulness behind well-structured, sensibly named endpoints, making them more likely to continue using your services.
What You Need to Know About RESTful API Development
With so many REST API endpoint naming conventions to worry about, it’s no wonder that building your own REST API can take such a long time. The good news is that it doesn’t have to, thanks to API management platforms like DreamFactory.
API development may sound complex, but with the right API management platform, you don’t even need to know how to write a single line of code.
A few things to keep in mind when choosing an API development platform:
- Security
- Built-in integrations
- 24/7 support
Frequently Asked Questions about Naming REST API Endpoints
Why is a consistent naming convention crucial in REST API endpoints?
Consistent naming conventions make your API predictable, easier to understand, and use. Developers can anticipate the structure of the endpoints, which leads to fewer errors and a more efficient integration process. It also enhances the readability and maintainability of your code.
What are the benefits of using nouns instead of verbs in naming REST API endpoints?
In REST, we conceptualize our data as resources. Using nouns to name endpoints aligns with this concept as it makes clear what resource the endpoint is exposing. Verbs, on the other hand, are better suited for defining actions, which in RESTful design, are represented by HTTP methods like GET, POST, PUT, and DELETE.
Why should we use plural nouns in REST API endpoint naming?
Using plural nouns is a common convention in REST API design. It helps ensure consistency and better reflects the possibility of the endpoint returning multiple resources. For example, /users could represent one user or many, while /user might imply it only represents a single user.
Can you explain the role of HTTP methods in REST API endpoints?
HTTP methods represent actions on the resources. The most common are GET (retrieve), POST (create), PUT (update), and DELETE (remove). By using these methods, we can simplify our endpoint names, focusing them solely on the resources.
Why should deep nesting be avoided when naming REST API endpoints?
Deeply nested endpoints can become complex and difficult to manage, leading to potential confusion and mistakes. It’s generally recommended to limit nesting to one level, i.e., /users/123/posts, instead of deeper nesting like /users/123/posts/456/comments.
How does proper REST API endpoint naming enhance troubleshooting?
Well-named endpoints make it easier to locate and correct problems. If the endpoint’s name reflects its function, developers can identify issues more quickly, enhancing productivity and reducing downtime.
How can proper endpoint naming facilitate the growth and scalability of my application?
As your application grows and the number of your API endpoints increases, a robust naming convention helps manage this growth effectively. Consistent and clear endpoint names ensure that new endpoints integrate smoothly with existing ones, thus facilitating scalability.
Reach out to DreamFactory and start your 14-day hosted trial today.
Terence Bennett, CEO of DreamFactory, has a wealth of experience in government IT systems and Google Cloud. His impressive background includes being a former U.S. Navy Intelligence Officer and a former member of Google’s Red Team. Prior to becoming CEO, he served as COO at DreamFactory Software.