Sign displaying best practices for naming REST API endpoints

REST APIs are a powerful tool for multiple applications or systems to communicate and exchange information according to the REpresentational State Transfer architectural pattern. While REST APIs are extremely useful, creating them and deploying them into production can be 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 doing so—including the best practices for naming your REST APIs. Using REST API naming conventions will dramatically lower the learning curve, making it easier for new developers and third-party users to get started with the API.

Did you know you can generate a full-featured, documented, and secure REST API in minutes using DreamFactory? Sign up for our free 14 day hosted trial to learn how! Our guided tour will show you how to create an API using an example MySQL database provided to you as part of the trial!

Create Your REST API Now

Below, we’ll go over 7 tips for naming REST API endpoints that you should follow.

1. Use nouns for naming 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 an Uniform Resource Identifier (URI). For example, the URI https://api.example.com/users will return a list containing the users of a particular service.

In general, 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. 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).

Using nouns for naming URIs is a REST API naming best practice, but when should you use singular or plural nouns? In general, using 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

When naming REST API endpoints, you should use URI names that are intuitive and clear—ideally, 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

REST APIs are typically structured in a hierarchy: for example, 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.

While forward slashes are good for denoting the hierarchy of your API, they’re not necessary at the very end of the URL, where they add complexity without adding clarity. For example, 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 (see below).

5. 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.

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.

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 (“|”).

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. 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.

If you want to specify the filetype of the results, you can use the Content-Type entity header instead.

Did you know you can generate a full-featured, documented, and secure REST API in minutes using DreamFactory? Sign up for our free 14 day hosted trial to learn how! Our guided tour will show you how to create an API using an example MySQL database provided to you as part of the trial!

Create Your REST API Now

Conclusion

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.

DreamFactory is a leading API management platform that can automatically generate and manage your REST APIs, without writing a single line of code. With ironclad security, dozens of built-in integrations, and 24/7 support, DreamFactory makes it easier than ever for organizations to digitally transform their business.

Try DreamFactory 4.8.0

DreamFactory 4.8.0 has been released! This release focuses on user experience, notably with regards to database API generation. The most popular database connectors (MySQL, MariaDB, PostgreSQL, MS SQL Server, and Oracle) have long included a lengthy list of options, and it hasn’t been obvious which are required and which are optional. To remedy this we’ve broken the service creation form into three sections: Basic, Caching, and Optional Advanced Settings. Additionally, because the Services tab is the natural first tab new users should be clicking on after logging in, we’ve moved the tab to the second position in the navigational bar directly following the Home tab.

In upcoming releases users will see a stream of additional UX improvements intended to more effectively guide new users through the API generation process. Notably, for most basic use cases the administrator completes three tasks: generate the API, create a role-based access control (RBAC), and then associate the RBAC with a newly generated API key. Therefore after successful API generation users will be presented with a new view enumerating typical next steps. We’re also working on improving the service profile detail page, providing admins with a link list taking them directly to the service’s relevant other administrative features, such as API Docs and associated roles.

Looking to get a handle on your own API management needs? Get in touch with our team today for a chat about your business objectives, or to start your free trial of the DreamFactory platform.

Related reading:

What are REST endpoints that JOIN table data?