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 we are not required 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 be covering 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 each and 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 very 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://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}

These are not rules.Neither way is right or wrong.Make sure to be consistent with your naming conventions.

 

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 long names are used for building URI.

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

Hyphens improve readability of the long URI.

 

2.5 Avoid underscores ( _)

It is recommended to avoid underscores while naming your URI. Here are some of the 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 ( _ )

If you prefer to use camelCase for naming your REST URI, You can use it without any second thought. Google Drive API use camelCase for the URI naming.

 

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 will not be able to understand what they can do with our API.

 

2.7 CURD Operations

While designing your URI, do not use it to indicate what CURD operation is being performed.

We should use HTTP method to describe what actions are performed on the given resource.

HTTP Method CURD Action
 GETRead Operation
 POSTCreate Operation
PUTUPDATE
DELETEDELETE

 

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 to read/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 

 

If you are starting with REST API, I highly recommend to get a copy of RESTful Web APIs

 

Summary

In this post, we briefly discussed REST Resource Naming guidelines. We covered some of the recommendations which can be used while designing our RESTful API.There is no universal answer or guidelines while naming REST API.There is 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

Umesh

Hello!! I am Umesh- an engineer by profession and a photographer by passion.I like to build stuff on the web using OSS and love to capture the world through my lens.

follow me on:

3
Leave a Reply

avatar
2 Comment threads
1 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
2 Comment authors
Umesh AwasthiRon Wheeler Recent comment authors

This site uses Akismet to reduce spam. Learn how your comment data is processed.

  Subscribe  
newest oldest most voted
Notify of
Ron Wheeler
Guest
Ron Wheeler

Good and useful advice. A lot of errors: REST services have no strict rule and we are free to implement it the REST services have no strict naming rules and we are free to implement it the For RESTful URI, Nouns are good as compare to 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. For RESTful URI, nouns are better than verbs (verbs are discouraged).As a rule of thumb, your URI should refer… Read more »

Umesh Awasthi
Admin
Umesh Awasthi

Hello Ron,

Thanks for pointing out all these issues.I have corrected these points and even found some additional issues in this article.

trackback
ETags for REST With Spring | Java Development Journal

[…] in the caching and reduce the data traffic. Conditional GETs allow a client to ask a server if a resource has changed. If it has not changed, it can assume it’s current knowledge is up to date. If […]