Designing REST API: Best Practices you Should be Following

REST API, widely admired by its ease of use and lightweight characteristics has proven to be a better option for meeting real-time needs emerging within short notice. When we venture out to design a RESTful API, we would possibly run into many complexities which were unforeseen before. Having said that, it is quite difficult to create and enforce a rigid set of rules since to design an API there are no standards specified by any authority. But to eliminate the complex issue it might pose, there are many presumed practices which will work as guidelines for architects designing their API.

Following is list of few practices which when implemented in due considerations will bring down the chances of technical issues.

  1. Right Abstraction and Terminologies

When an URL which was once existing with a certain web content, throws 404 error, it will be quite exasperating from the user perspective. Similarly, an API should follow standard abstraction to shun the obligation of changing URLs later. Redirects can solve the issue, but from the user point of view, it exhibits the delay in loading of the page which he in no way cherish.

Also, there is a chance of business jargons and terminologies getting defined during designing of an API. If that happens, it will pose the contradictions for coding conventions. Once, I personally came across a situation where we were not able to use the word “document” only because it was a predefined parameter in that API.

2. Specific names, but not action based ones

When a API URL is over-loaded with the verbal suggestions, it might mislead the developer working on it. Hence it is assumed practically correct to define an URL in such a way that it will have nouns than verbs.

For ex: Consider a URL mediumgameapi.com/getaccounts. Here the term getaccounts seems to be suggestive of the action we are trying to do. If that is the case, when we use it with other HTTP verbs like PUT, POST etc, it proves to be counter-intuitive.

If they are used as POST mediumgameapi.com/getaccounts, it give the feeling that our objective is contradicting the URL structure.

Hence it is assumed to be better to have it in non-verbal format. For example, if it is mediumgameapi.com/accounts, it can be preceded with any HTTP methods like

GET mediumgameapi.com/accounts
PUT mediumgameapi.com/accounts
POST mediumgameapi.com/accounts
DELETE mediumgameapi.com/accounts

3. Two set of simple base URLs

Two set of base URLs are required to every source, one for drawing all the values and other for making it selective by using specific IDs. Consider a HTTP GET method where you want to pull all the account details and also draw details of a specific account. The specific account details can be drawn by using the account ID in the link. Following example shows how it can be done.

HTTP GET(read)
GET mediumgameapi.com/accounts — To draw all the account details
GET mediumgameapi.com/accounts/00928376 — To get account details using specific ID.

4. Clear URL hierarchy

An URL should have clear hierarchy defined so that when it is used it should give you a clear understanding of what the URL will do without describing it in detail. That will make the developers think less on conventions and enable them to understand intuitively. For ex:

GET /accounts/00928376/transaction/8738903

The above URL shows two level hierarchy which draws account details of ID 00928376 in first step and in second step it asks for transaction details with a specific ID. An URL can be designed to have any number of hierarchical modules, but from the conventional perspective it is good to have not more than three level traversing(Explained in next point). But again, it depends completely on business scenario.

5. Limited Levels of URL

As I mentioned earlier, it is good to limit the levels of URL to three. If a specific account transaction details in needed with the time and location of the transaction happened, it is good to use query string rather than scaling up the URL hierarchy.

For ex: GET /accounts/00928376/transaction/8738903/zip/6500/city/dublin/state/ca

In the above URL, we are trying to draw the transaction location with its Zip code, City and State. But the levels of URL has scaled up to five. Hence it is better to use a query string as shown below.

GET /accounts/00928376/transaction/8738903?zip=6500&city=dublin&state=ca

The above example intuitively shows two different stages of information seeking. One stage shows the URL levels drawing transaction details and remaining part as a query string which filters the details we are seeking