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
