Laptop screen showing best practices for naming REST API endpoints.

REST APIs are a powerful tool to bring together multiple applications. They allow these applications or systems to communicate and exchange information according to the Representational State Transfer architectural pattern. 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.

Knowing best practices for naming your RESTful APIs is particularly important. Using REST API naming conventions dramatically lowers the learning curve and makes it easier for new developers and third-party users to start with the API. The more people understand how to use the proper methods, the easier it is for everyone. These standards should be required for every URI naming process.

Below, we’ll go over the top tips for naming REST API endpoints.

DreamFactory Hosted Trial Signup

Generate a full-featured,documented, and secure REST API in minutes.

Sign up for our free 14 day hosted trial to learn how.

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.

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.

DreamFactory Hosted Trial Signup

Generate a full-featured,documented, and secure REST API in minutes.

Sign up for our free 14 day hosted trial to learn how.

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

Reach out to DreamFactory and start your 14-day hosted trial today.