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
