This is the 11th day of my participation in Gwen Challenge. For details, see Gwen Challenge.

There are many reasons to be thoughtful about naming API endpoints. Choosing the right name for an API endpoint can greatly smooth the learning curve for new developers, helping them intuitively know what to look for and where to find it, and greatly reduce the cost of communication between developers. This article introduces a practical specification for NAMING API endpoints. For REST design guidelines, see the 9 Basic Principles of REST API Design. Before we discuss API naming practices, let’s talk about resource naming guidelines for REST.

RESTful Resource naming rules

Let’s start with reST-specific naming guidelines, some of which apply equally well to other styles of API, but are common in naming RESTful API “endpoints.”

According to Roy T. Fielding himself, there is no such thing as a “REST endpoint.” There are resources, a set of resources that are limited only by the length of the URL. Resources are usually used as a subset of endpoints.

The noun URI is used as the resource

One of the easy-to-understand features of REST is the use of nouns primarily in URIs. RESTful URIs should not use any type of CRUD (Create, read, update, delete) functionality, and URIs should be used to uniquely identify resources, not to do anything with them. Therefore, the REST API should allow resources to be manipulated through an HTTP method, and resources should be in the form of nouns.

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

“RESTful URIs should refer to the resource of a thing (noun), not to an action (verb), because nouns have properties that verbs don’t — just like resources have properties.” – RESTfulAPI.net

Diversified resources

Next comes the question of whether resource names should be plural. Obviously, this is a matter of preference, but experienced API designers would recommend diversifying all resources unless they are a single resource.

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

Using a backslash/Representation hierarchy

As shown in the example above, the slash/is commonly used to show hierarchies between individual resources and collections.

For example: : /users/{id}/address clearly belongs to the /users/{id} resource, which belongs to the/Users collection.

“Hierarchy: Nothing is mandatory, just make sure the imposed structure makes sense for development. As with all things in the software development process, naming is key to success.” – RESTAPITutorial.com

A list of punctuation marks

When there is no hierarchy (as in a list), punctuation such as a semicolon or the common comma should be used.

For example, /users/{id1},{ID2} access multiple user resources.

Query parameters if necessary

For sorting or filtering collections, the REST API allows query parameters to be passed in urIs. For example: / users? Location =shenzhen Finds all users in Shenzhen

Use a hyphen-Improve readability

To make URIs easy for developers to understand, it is recommended to use hyphens to improve the readability of long, long names.

For example: /users/{id}/ pending-Orders instead of /users/{id}/ pendingOrders

Don’t use underscores_

Although it is possible to use underscore _ instead of hyphen – as a separator, for some applications, the underscore _ character may be partially or completely obscured in some browsers or screens.

To avoid this confusion, it is recommended to use a hyphen – instead of an underscore _.

For example: /users/{id}/pending-orders instead of /users/{id}/pending_orders

Use lowercase letters

RFC 3986 defines urIs as case-sensitive. Case-sensitive URIs represent different paths in different environments. To avoid confusion, it is recommended to always use lowercase letters in urIs.

Endpoint resource naming

Common REST API resource naming conventions were introduced above, however, there are some general naming conventions that should be adhered to regardless of whether the API is RESTful or not.

Intuitive names (no jargon)

Make endpoint names more intuitive! Wherever possible, choose the simplest and most commonly used words to replace a given concept. If done correctly, most endpoint/resource names should be able to guess their purpose, so developers don’t have to look at API documentation.

As an extension of this, avoid jargon. Knowledgeable developers may have no problem with jargon, but most developers don’t necessarily know the industry jargon.

Do not omit (do not abbreviate)

Avoid omitting endpoint/resource names. Modern WEB technologies, network environments, and devices make this unnecessary. In fact, abbreviated names can actually create confusion in the API, making it difficult for developers to guess (and sometimes even understand) the name chosen.

For example, /users/{id}/phone-number replaces /users/{id}/tel-no

No extension

Do not use file extensions (such as.xlsx) in urIs, which are relatively ugly and add length to urIs. To specify the format of the Content, you are advised to use content-type.

For example, /users/{id}/pending-orders replaces /users/{id}/pending-orders. XLSX, content-type :application/vnd.ms-excel; charset=utf-8;

No diagonal/At the end

Also, to keep urIs clean, don’t add a slash/to the end of a URI. This adds semantic value and can lead to confusion.

For example: /users/{id}/pending-orders instead of /users/{id}/pending-orders/

Trailing slashes must have no specific semantics, and resource paths must provide the same result whether they have trailing slashes or not. — Zalando RESTful apis and Event Guidelines

Consistency is key

Consistent naming of endpoints is a must, and even if the convention is strictly followed, the API will always be uncomfortable with inconsistent names. Always refer to a given resource by the same name in the API.

The endpoint naming conventions described in this article are one-sided and there will be more friendly specifications in actual development, but regardless of the specification style, you need to ensure that the endpoint names are consistent with the names used in the documentation and, if applicable, the application itself.

For example: /users should be logged under the Users resource, not the getUser method.

conclusion

This is a summary of some of the naming conventions for API endpoints/resources that a project can use. A simple and intuitive naming convention is definitely developer-friendly! Zalando RESTful API and Event Guidelines are recommended for more granular API design specifications.