Guidelines & Best Practices for Design RESTful API

API development is increasing significantly as they serve the most important use case to build dynamic applications that exchange information. In other words, Restful API is used to connects devices and allow the sharing of data. API exchanges the data between server & client i.e to receive requests from the client and sends a response back.

API Jargons

The term API is an acronym, and it stands for “Application Programming Interface.” API allows applications to exchange data via endpoint to which client sends a request and receives back data. It’s like communication services between two devices.


The term REST is an acronym, and it stands for Representational State Transfer. Rest is an architectural paradigm used in the development of web services. First presented by Roy Fielding


Also, know as a RESTful web service. Web services that conform to the REST architectural style & uses HTTP methods, termed RESTful web services.

In general, API makes the work a lot simpler and easier. It allows the developer to integrate functionality from third-party services rather than building themselves from scratch. As an example, Uber & Ola is using Google Map for a navigation system. This helps them to save time rather than building a navigation system from scratch.

Guidelines & Best Practices for Design RESTful API

RESTful API Design

Let’s take an example for Resource type Article, to have a better understanding of designing API’s.

API can be built in any server-side programming language like PHP, Ruby, JS, Java, Python, Go-lang, Elixir. Many popular libraries & frameworks are built to develop Rest API’s like Django, Express, Rails, Spring. These help the developer to speed up the development process.

Let’s start designing restful API by following REST architect.

To GET Record

Bad designs

GET /FetchArticle                   # To fetch all records
GET /getAllArticles/12              # To fetch specific records

Preferred Designs

GET /articles                       # To fetch all records
GET /articles/12                    # To fetch specific records

To Crete Record

Bad designs

POST /createarticle                 # To create article
GET  /createrecordforartilce        # To fetch all records

Preferred designs

POST /articles                      # To create article records

To Update Record

Bad designs

PUT  /updatearticle/id               # To update article
POST /id/modifyarticle               # To update article

Preferred designs

PUT /articles/:id                     # To update article

To Delete Record

Bad designs

DELETE /deletearticle/id              # To delete article
POST   /id/removearticle              # To delete article

Preferred designs

DELETE /articles/:id                # To delete article

HTTP methods 

GET, POST, PUT, DELETE is the most common HTTP method used to indicate the desired action to be performed at a given resource. HTTPS verbs, tell what action should be performed at the requested resource.

HTTP response status codes

To tell the consumer that requests should be failed or passed by the server. The standard HTTPs code is introduced and the server returns these generic status codes.


Documentation is an important metric for a developer to use the API. Different API have different behavior which requires different parameters such as  HTTPS methods, API response. Developer loves good documentation.

Various good tools are available in the market to help developer to generate the API documents.


API security is the important aspects, having a vulnerability in the system opens a way for an attacker to perform malicious activity. Before deployment of restful API. Developer has to identify the vulnerabilities & fix the potential security bugs ASAP otherwise, it threatens the company’s database.


Versioning is important especially when we have third-party clients. It is always good practice to versioning the API as all the latest changes move towards the new version and older changes remain in the previous version. So that the existing app doesn’t get a break by new changes and developers get enough time to reflects these changes into the existing app.

It’s useful to put the version in the URL not mandatory.  Versioning can also be achieved with Custom Request Header means the client passes the api-version in header.

URI Versioning


Characteristics of Good Restful API’s

How to scale the API


All REST APIs are APIs, but not all APIs are REST APIs. Good designed API is always simple to use & admired by developers.

Following point are only my personal opinion. These are not fixed rules, but only tips from my own years of experience!

Also, see

Exit mobile version