RESTful API Endpoint— Naming Convention

Designing RESTful APIs is a topic that is covered by many. But with all that content available, it quite a cumbersome tasks to select out the best approach to be taken for naming RESTful API endpoints which follows the standards. Therefore, in this mini article we will be looking into a simplified analysis of the what I consider is a good approach to take when naming your RESTful API Endpoints.

Identify the resources

Firstly you have to identify what resources you can identify from a given scenario. This can be the nouns. For example, user, game, weather, etc. But make sure that you don’t make or share secure implementation details with your API consumers.

Identify the action to be applied

The next step you have to identify is what actions can apply to your identified resources.

Existing HTTP Methods, help in implementing CRUD operations to an endpoint. All the CRUD operations can be used towards a single endpoint which has been generated. Example shown below:

GET /users
POST /users
PUT /users/12
DELETE /users/13

Decide on whether a endpoint should be singular or plural

To make it easier for you always go for plural API endpoint naming convention, so you do not have to deal with odd pluralisation.

Dealing with relations

The RESTful guide provides tips on how you can structure your API if any relations exist for a resource. For example:

GET /users/15/posts 

The above endpoint retrieves the list of posts for user #15. To deal with these relations you can take 2 approaches:

• Approach 01: If the identified relation can exist without a resource then it’s best to include an identifier for it within the output representation of the resource.
• Approach 02: If an independently existing relation is commonly requested alongside the resource, then the API could offer functionality to automatically embed the relation’s representation. This automatic embedding can be done by including embed or expand as query parameters.

Separate words with hyphens

If an endpoint contains multiple words the best practise is to use hyphens instead of underscore characters or camel-casing. The use of capital letters are discouraged when naming API endpoints.

Use lowercase letters

The RFC 3986 specification for URI standards, specify that API URLs should be in lowercase standard. Lowercase characters for URIs are in widespread use, and also help avoid confusion about inconsistent capitalisation.

Avoid special characters and File Extensions

Try to avoid the use of certain special case characters which mostly tend to be “Unsafe” ASCII characters. These are usually encoded such as the space character represented by “%20". Furthermore, it’s also a best practise to avoid the use of file extensions, since the change in the file type can cause certain issues for the end user.

Author: Dilmi Kottachchi