Designing REST APIs Best Practices

REST APIs, widely admired for their ease of use and lightweight characteristics, have proven to be the better option for meeting real-time needs with short notice. When we venture out to design a RESTful API, we might run into complexities that 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. To eliminate the complex issue it might pose, there are many presumed practices that will work as guidelines for architects designing their API.

Following is a list of a few practices that can reduce the chances of technical issues.

1. Right Abstraction and Terminologies

When a URL that was once existing with a certain web content throws a 404 error, it can 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's point-of-view, there's a delay in loading of the page.

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 an API URL is overloaded with verbal suggestions, it might mislead the developer working on it. Hence, it is assumed practically correct to define a URL in such a way that it will have nouns than verbs.

For example, consider the 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 counterintuitive.

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

Hence, it is assumed to be better to have it in nonverbal 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 Sets of Simple Base URLs

Two sets 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 an HTTP GET method where you want to pull all of 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. The 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

A URL should have a 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 example:

GET /accounts/00928376/transaction/8738903

The above URL shows a two-level hierarchy that draws account details of ID 00928376 in the first step, and in the second step, it asks for transaction details with a specific ID. A 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 (I will explain this in the next point). 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. The levels of URL has scaled up to five, so 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.