DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
Building Scalable Real-Time Apps with AstraDB and Vaadin
Register Now

Trending

  • VPN Architecture for Internal Networks
  • Micro Frontends on Monorepo With Remote State Management
  • Five Java Books Beginners and Professionals Should Read
  • Designing a New Framework for Ephemeral Resources

Trending

  • VPN Architecture for Internal Networks
  • Micro Frontends on Monorepo With Remote State Management
  • Five Java Books Beginners and Professionals Should Read
  • Designing a New Framework for Ephemeral Resources
  1. DZone
  2. Software Design and Architecture
  3. Integration
  4. Designing REST APIs Best Practices

Designing REST APIs Best Practices

REST APIs are the best option for meeting real-time needs with short notice. Read on to learn some best practices for working with them.

Pradyumna Kulkarni user avatar by
Pradyumna Kulkarni
·
Dec. 05, 16 · Opinion
Like (11)
Save
Tweet
Share
10.84K Views

Join the DZone community and get the full member experience.

Join For Free

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. 

REST Web Protocols

Published at DZone with permission of Pradyumna Kulkarni. See the original article here.

Opinions expressed by DZone contributors are their own.

Trending

  • VPN Architecture for Internal Networks
  • Micro Frontends on Monorepo With Remote State Management
  • Five Java Books Beginners and Professionals Should Read
  • Designing a New Framework for Ephemeral Resources

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: