REST Resource Naming Guide

REST Resource Naming

In our previous article, we learned how to validate REST API data.In this article, we will discuss REST Resource Naming guidelines. These are just guidelines and it does not require us to follow these guidelines as is.

 

Introduction

REST services have no strict naming rule and we are free to implement it the way we want, however, there are certain guidelines which ensure that our REST API is 

1. Simple to read
2. Consistent
3. Intuitive

We will cover REST Resource Naming guidelines in this post 

 

1. Keep it Simple

This is not specific to resource naming guidelines but an important concept while designing your API.Our REST API naming should be self-describing and as simple as possible.One of the important principle while naming our API is to allow developers to work on it without referring to the documents for every point.

Let’s have a look at following 2 examples

/users/12345
/api?type=user&id=12345

Looking at the second example, it is not clear what we are trying to do until we look at the type and id field together.

 

2. REST Resource Naming

 

2.1 Use Nouns for Naming

For RESTful URI, Nouns are better than verbs (verbs are discouraged).As a rule of thumb, your URI should refer to a thing (a noun) and not an action (verb).The reason for using noun is your API is its ability to represent properties.

some examples

1. User
2. User Account
3. User’s Order
4. Products

Here is the resource URL example

https://javadevjournal.com/rest/v1/users
httpa://www.javadevjournal.com/rest/v1/users/{userId}

https://javadevjournal.com/rest/v1/users/{userId}/orders
https://javadevjournal.com/rest/v1/users/{userId}/orders/{code}
https://javadevjournal.com/rest/v1/orders/{code}


https://javadevjournal.com/rest/v1/products/{productCode}

Do not use RPC way to create your REST API’s

https://javadevjournal.com/rest/v1/getUsers
https://javadevjournal.com/rest/v1/getOrder

 

2.2 User Plural Nouns for Naming

You can choose singular nouns for naming your RESTful URI’s but it is recommended to use plurals nouns for naming your RESTful APIs.As one of the most common operations performed by the REST API is to get data, using plural is more intuitive and easy.Keep in mind following points

• Do not mix singular and plural convention while naming your resources.It should be consistent across the API for readability.
• URL represents a resource which can be a singleton or a collection.A plural represents all resources under given URI
  • /customers represent all customers.
  • /customers/{id} represents specific customer under this resource.
• Given resource can also contain sub-collections.Think about all the orders placed by the customer in an online shop.
  • /customers/{id}/orders
  • /customer/{id}/orders/{order-id}

[pullquote align=”normal”]These are not rules.Neither way is right or wrong.Make sure to be consistent with your naming conventions. [/pullquote]

 

2.3 Use Lowercase

If possible, use lowercase letter while constructing your URL paths

/customer/{id}/orders/{order-id}
/customer/{id}/addresses/{address-id}

//Not recommended
/customer/{id}/Addresses/{address-id}

 

2.4 Use Hyphens (-)

Use hyphens (-) in case we use long names for building URI.

/customers/{id}/addresses/{address-id}
/customers/{id}/shipping-addresses/{address-id}

Hyphens improve readability of the long URI.

 

2.5 Avoid underscores ( _)

We recommend avoiding underscores while naming your URI. Here are some reasons to do this

• Underscores can create confusion if application front is not correct or may become hidden in some browsers or screens.

Prefer hyphens ( – ) over underscores ( _ )

[pullquote align=”normal”]If you prefer to use camelCase for naming your REST URI, You can use it with no second thought. Google Drive API use camelCase for the URI naming. [/pullquote]

 

2.6 Concrete Names over Abstraction

Prefer concrete items over abstraction.Let’s take a simple example of representing our “Order” model in the REST API. 

If we go by abstraction, we may want to represent it as an item /items, but this will make our API hard to read and understand. The consumer of our API cannot understand what they can do with our API.

 

2.7 CURD Operations

While designing your URI, do not use it to show what CURD operation is being performed.We should use HTTP method to describe what actions are performed on the resource.

[thrive_highlight highlight=’default’ text=’light’]

HTTP Method	CURD Action
GET	Read Operation
POST	Create Operation
PUT	UPDATE
DELETE	DELETE

[/thrive_highlight]

 

HTTP GET https://javadevjournal.com/orders  //Get all orders
HTTP GET https://javadevjournal.com/orders/{order-id}  //Get order based on order code
HTTP POST https://javadevjournal.com/users  //Registers a customer.

HTTP PUT https://javadevjournal.com/users/{userId}  //Updates customer profile.
HTTP DELETE https://javadevjournal.com/users/{userId}  //Removes customer profile

 

 

2.8 Filter Operations

While building RESTful APIs, we will come across multiple requirements where we need collection of resources with

• Sorting
• Filtering our certain results from the collection.
• Limited results based on certain conditions 

Do not create new API for these requirements.Use query parameters to achieve all these results.

https://javadevjournal.com/products?catalog=Online
https://javadevjournal.com/products?region=USA&brand=dummy&sort=new

 

3. Furthur Reading

We covered some of the basic guidelines for the REST Resource Naming. I Strongly recommend reading/watch following additional resources.

1. REST URI convention – Singular or plural
2. Are there any naming convention guidelines for REST APIs?
3. REST-Ful API Design 

 

[pullquote align=”normal”]If you are starting with REST API, I highly recommend to get a copy of RESTful Web APIs [/pullquote]

 

Summary

In this post, we briefly discussed REST Resource Naming guidelines. We covered some recommendations which can be used while designing our RESTful API.There is no universal answer or guidelines while naming REST API. There are a lot of discussions, a debate is happening to come up with REST best practices.

In the next articles of the REST with Spring series, we will cover following topics

• HTTP Methods for REST 
• HTTP Headers