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

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

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


http://www.javadevjournal.com/rest/v1/products/{productCode}

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

http://www.javadevjournal.com/rest/v1/getUsers
http://www.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 http://www.javadevjournal.com/orders  //Get all orders
HTTP GET http://www.javadevjournal.com/orders/{order-id}  //Get order based on order code
HTTP POST http://www.javadevjournal.com/users  //Registers a customer.

HTTP PUT http://www.javadevjournal.com/users/{userId}  //Updates customer profile.
HTTP DELETE http://www.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.

http://www.javadevjournal.com/products?catalog=Online
http://www.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

4 thoughts on “REST Resource Naming Guide”

  1. It is interesting that point 2.2 stresses that you should use plural nous for naming, while 2.3 uses a singular customer.

  2. 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 to a thing (a noun) and not an action (verb).The reason for using nouns in your API is its ability to represent properties. – capitals in mid-sentence is your API-> in your API

    If you prefer to use cameCase for naming your REST URI, You can use it without any second thought. Google Drive API use camelCase for the URI naming.
    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.

    In the nest articles of the REST with Spring series, we will cover following topics
    In the next articles of the REST with Spring series, we will cover the following topics: nest->next

Comments are closed.

Scroll to Top