REST Webservices naming guidelines

In REST there is no strict naming rule conventions but there are certain guidelines which ensure that our webservices api URLs are easy to read and understand.

We are free to implement it in any way we want to.

Naming guidelines of REST WebServices

Just remember Nothing is right or wrong here in naming REST URIs as these are not the rules but best practices.

1. Simple Names

As such nothing specific, but the naming of REST API should be self-describing and simple.

Example

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

2. Use Nouns not verbs

Your URI should refer to a thing (a noun) and not an action (verb).

Example

http://www.programmertoday.com/rest/v1/users
http://www.programmertoday.com/rest/v1/users/{userId}
http://www.programmertoday.com/rest/v1/users/{userId}/orders
http://www.programmertoday.com/rest/v1/users/{userId}/orders/{order-id}

http://www.programmertoday.com/rest/v1/orders/{order-id}

http://www.programmertoday.com/rest/v1/products/{product-id}

we must avoid using uri names like below:
http://www.programmertoday.com/rest/v1/getUsers
http://www.programmertoday.com/rest/v1/getProducts

3. Try using Plural Nouns

Though name can be in singular noun as well but well recommended is to use plural nouns.

Example

/employees which represents all employees
/employees/{emp-id} represents a particular employee

4. Use lower case

Example

Recommended
/employees/{emp-id} 

Not-Recommended
/Employees/{emp-id}

5. Use Hyphens(-) to sepreate two words

Example

/employees/{emp-id}

6. Do not use Underscores(_)

Because Some search engines and browsers may concaternate the two words seperated by underscore.

Example

Not-Recommended
/employees/{emp_id} 

7. Filters like pagination, Limited search, sorting

For requirements like these, we should not go and create seperate resources Rather we should use query params to achieve the same.

Example

http://domain/rest/v1/orders?orders=Online

http://domain/rest/v1/products?category=toys&within=100

8. Do not name APIs with HTTP methods for CRUD operations

Example

HTTP GET : http://domain/rest/v1/products/{product-id}

HTTP DELETE : http://domain/rest/v1/products/{product-id} 

Not-recommended
http://domain/rest/v1/getorders
http://domain/rest/v1/remove/products
http://domain/rest/v1/delete/products
http://domain/rest/v1/updateproduct

9. Versioning

Always version your API. Versioning helps you iterate faster and prevents invalid requests from hitting updated endpoints. It also helps smooth over any major API version transitions as you can continue to offer old API versions for a period of time.

Example

HTTP GET : http://domain/rest/v1/products/{product-id}

HTTP GET : http://domain/rest/v2/products/{product-id}

Summary

In this tutorial, we learnt about the REST Webservices naming guidelines which one should follow not as a rule but as a good practice.
I hope you liked it !

---