There are plenty of reasons to name API endpoints thoughtfully. Choosing sensible names for API endpoints can drastically smooth out the learning curve for new developers, helping them intuitively know what to look for and where to find it. With that in mind, we’re dedicating this article to more than ten of the most effective best practices and conventions for naming API endpoints. First, we’ll discuss some REST-specific resource naming principles, and then we’ll move onto some more universal guidelines.

RESTful Resource Naming Conventions

Let’s kick things off by looking at some REST-specific naming conventions. While you might find some of these naming practices applied to other API design styles, they’re most commonly seen in the naming of RESTful API “endpoints.”

Disclaimer: According to Roy Fielding himself, there’s no such thing as a “REST endpoint.” However, in common parlance, resources are considered a subset of endpoints.

1. URIs as resources as nouns

One of the most recognizable characteristics of REST is the predominant use of nouns in URIs. RESTful URIs should not indicate any kind of CRUD (Create, Read, Update, Delete) functionality. Instead, REST APIs should allow you to manipulate a resource — which should take the form of a noun — through one of the main HTTP methods.

Example: /users/{id} instead of /getUser

“RESTful URIs should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes.” – RESTfulAPI.net

2. Pluralized resources

Next up is the question of whether resource names should be pluralized. Admittedly, this is a matter of preference; however, most API design experts would suggest you pluralize all resources unless they are singleton resources.

Example: /users (typical resource) or /users/{id}/address (singleton resource)

3. Forward slashes for hierarchy

As shown in the examples above, forward slashes are conventionally used to show the hierarchy between individual resources and collections.

Example: /users/{id}/address clearly falls under the /users/{id} resource which falls under the /users collection.

“There aren’t any hard and fast rules [for hierarchy], only make sure the imposed structure makes sense to consumers of your services. As with everything in the craft of Software Development, naming is critical to success.” -RESTAPITutorial.com

4. Punctuation for lists

When there is no hierarchical relationship (such as in lists), punctuation marks such as the semicolon, or, more frequently, the comma should be used.

Example: /users/{id1},{id2} to access multiple user resources

5. Query parameters where necessary

In order to sort or filter a collection, a REST API should allow query parameters to be passed in the URI.

Example: /users?location=USA to find all users living in the United States

6. Lowercase letters and dashes

By convention, resource names should use exclusively lowercase letters. Similarly, dashes (-) are conventionally used in place of underscores (_).

Example: /users/{id}/pending-orders instead of /users/{id}/Pending_Orders

General Endpoint Naming Best Practices

The above naming conventions are typically associated with REST APIs. However, there are a good handful of general naming conventions you should stick to regardless of whether your API is RESTful or not! Here are just a few of them:

7. American English

Stick to using American English for your endpoint/resource names, since it’s the dialect your international audience of developers is likely most familiar with. The exception to this would be if your API targets a specific national audience that predominantly uses a different dialect (e.g. British or Australian).

Example: /airplanes instead of /aeroplanes

8. Intuitive names (no jargon)

Make your names intuitive! Wherever possible, choose the simplest and most commonly used word to refer to a given concept. If done correctly, the majority of all endpoint/resource names should be guessable, saving developers from having to trawl through your documentation.

As an extension of this, avoid using jargon. More knowledgeable developers won’t have any trouble guessing the simpler variant of a word, but the average developer won’t be able to guess a technical term they haven’t heard before!

Example: /users/{id}/card-number instead of /users/{id}/pan

Speaking on naming practices for APIs, at our 2019 Platform Summit, Rahul Dighe recommended less domain-centric jargon. “Something that’s common and more understandable is going to make your APIs a lot more usable,” said Dighe.

9. No abridging

Avoid abridging endpoint/resource names. What with modern-day technology, there’s really no need. In fact, abridged names can actually create confusion in your API, as developers struggle to guess (and sometimes understand) the names you’ve chosen.

Example: /users/{id}/phone-number instead of /users/{id}/tel-no

10. No file extensions

Leave file extensions (such as .xml) out of your URIs. We’re sorry to say it, but they’re ugly and add length to URIs. If you need to specify the format of the body, instead use the Content-Type header.

Example: /users/{id}/pending-orders instead of /users/{id}/pending-orders.xml

11. No trailing forward slash

Similarly, in the interests of keeping URIs clean, do not add a trailing forward slash to the end of URIs.

Example: /users/{id}/pending-orders instead of /users/{id}/pending-orders/

“The trailing slash must not have specific semantics. Resource paths must deliver the same results whether they have the trailing slash or not.”

• Zalando RESTful API Guidelines

Consistency is Key!

Consistency is an endpoint naming principle that deserves special recognition. No matter how closely you follow our above suggestions, your API will always feel clumsy if names are inconsistent. Always use the same name(s) to refer to a given concept within your API.

Keep in mind this guide is simply a suggested compilation of endpoint naming best practices, and others may adopt variants in practice. Most importantly, whatever style you adopt should be applied universally. Similarly, make sure that endpoint names are consistent with names used in the documentation and, if applicable, in the application itself.

Example: /users should be documented under the users resource instead of the getUser method

Benefits of Following Naming Conventions

Following best practices for endpoint naming might not seem like the biggest deal. After all, API developers already have enough to worry about, like new security vulnerabilities and creating successful API-first products. But, with a bit of forethought, adopting naming conventions can improve developer experience, scalability, and ongoing maintenance down the line. Here are three potential benefits.

• Naming consistency boosts the developer experience. Having naming consistency across your API and your API portfolio can increase learnability and decrease friction when integrating for the first time. The result is less confusion and less time required to get to that Hello World moment.
• Your API will resemble the standards developers have come to expect. There are many rules, sometimes unwritten, regarding modern API design. Fitting into these best practices helps communicate that you, as a software provider, are aware of the industry at large and indicates a more dependable, interoperable system.
• Coalescing on coding style aids ongoing evolution. Standardizing on internal programming styles will make your APIs more adaptable to evolution and help to retain scalability for the long term. Especially if these conventions are documented and shared, a consistent style will help direct feature changes as well as the creation of more internal services.

Final Thoughts

There you have it: a handful of the most influential conventions and best practices for naming API endpoints — RESTful and otherwise. From the more technical issues, such as showing resource hierarchy, to the more linguistic ones, such as using American English, this concise collection of naming principles is sure to please even the strictest developers! For more fine-grained API design conventions, we recommend the API Stylebook curated by the API Handyman. It has loads of quality information, showcasing API design style guides from many companies.