Monday, September 24, 2018

Principles Of Designing Of Restful APIs

This blog will covers the basic principles of designing of restful APIs and I will use ASP.NET Web API as example to elaborate the designing principles with proper practical example.

In a day to day life, most of software developer creates Web API project and publish Web API as internal service for internal application or publish as external service to external clients.

If developer follows these principles while designing the APIs it avoids common mistakes and helps to build the consistence, reliable and robust APIs. 

·         Use NOUNS and NOT the verbs
·         Use the HTTP Verbs
·         Use the Plurals
·         Use Query Parameters
·         Use the Proper HTTP Code
·         Versioning
·         Use Pagination Concept for Huge Data 

Use NOUNS and NOT the verbs:

It’s a very common mistake what develop make, they starts using verb in API URL and trying to explain the APIs functionalities by using the method name like GetAllProjects or CreateProject b but in Rest API, the HTTP Verbs can better describes the API instead of using method name in URI


GET all Projects:



Create Project:


To avoid above common mistake, we need to use NOUNS instead of Verbs


GET all Projects:


Create Project:


Use the HTTP Verbs

HTTP verbs are known as method just like resource are nouns and HTTP verbs defined the type of operation of REST API

HTTP Verb Semantic
GET Retrieve a single resource or collection of resource 
POST Create a new resource
PUT Completely replace a resource
PATCH Partially update a resource
HEAD Retrieve only header information of response
DELETE Delete the existing resource

Use the Plurals

Keep the resource URL name the plurals instead of singulars and if you are using singulars or plurals name convention, make consistence.

API/Projects --------- plurals

API/Project ---------- singulars, in case of get ALL project resources, it will be confusing

Use Query Parameters
Most of time, we need to filter the resource by passing ID or Code.

Get Project Resource by Project ID

HTTP GET API/Projects/1000

Get Project Resource by Project Code

HTTP GET API/Projects/Code/PJ1212

In some scenario, we need to pass more than one filters so the query parameter should be used for Restful API designing.

HTTP GET API/Projects?City=Houston&Type=IT

Use the Proper HTTP Code

While designing the restful API, we need to make sure that API should always return the right and consistence HTTP status Code and without consistent HTTP status codes, customers will not know the difference between success or failure without parsing the response body

HTTP standard provides almost 70 HTTP status codes to describe the HTTP Response status and you can use below HTTP status code for restful API. 

200 – OK
204 – OK – No Content
400 – Bad Request
401 – Unauthorized
500 – Internal Server Error
503 – Service is not available 


Versioning is very important feature of API and it is always advisable that publish API with version code so you can easily distinct between current version and previous version of API and it helps us to support backward compatibility and customer get time to transition from current version to next version.

There are many ways to maintain the versioning of API by using API URI, Header or query parameters.

HTTP GET:  API/v1/Projects

HTTP GET:  API/v2/Projects

Use Pagination Concept for Huge Data

In case of API returns huge data, it is advisable to use pagination concept and display only allowable size of data.

You can use PageSize and CurrentPage logic to implement pagination or limit & offset logic 

HTTP GET:  API/v1/Projects?PageSize=25&CurrentPage=2


HTTP GET:  API/v1/Projects?limit=25&offset =25

SQL Server - Identify unused indexes

 In this blog, we learn about the index usage information (SYS.DM_DB_INDEX_USAGE_STATS) and analyze the index usage data (USER_SEEKS, USER_S...