The Basic 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

Eg.

GET all Projects:

API/GetAllProjects

Or

Create Project:

API/CreateProject

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

Eg.

GET all Projects:

HTTP GET API/Projects

Create Project:

HTTP POST API/Projects

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

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

OR

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