Best Practices for REST API Design

Play Voice
November 28, 2024
Technology

API development is now a cornerstone of modern, web-enabled applications. In the past, API calls were often quite rare, and most usually done using third-party API such as those for checking bank account numbers or looking up postal addresses using a zip code. This was a simple situation. Unfortunately, with the ever growing complexity of interlinked web enabled apps, APIs are now often the underlying power of current gen web apps. We can no longer languish in the luxury of simply using third-party API, we now develop them internally to access business side resources as well. So below, here are a few very basic best practices for designing REST API:

1) Good Design is Key

In order to make sure that an API not only functions but continues to function with limited ongoing maintenance, it is a good idea to standardize API design across a project. The advantage of doing this is that if later application changes require modification of core API details such as the URL, then a standard pattern of modification will fit every single API.

2) Only Nouns Not Verbs

This is a pretty fundamental concept when it comes to designing APIs. Using a verb in the APU URL won’t necessarily stop it from working, but it does muddy the waters when it comes to future API maintenance. Check this example:            domain.com/getbookingsLooks sensible right? Yes, it does when we use the API with a GET request. But it doesn’t make so much sense with a POST, DELETE or PUT request. The danger is, that down the line a developer instinctively believes that an API with a getbookings URL is only used for a GET request. So instead, we just use the noun:            

domain.com/bookings

And then every post type makes sense:

GET domain.com/bookings
PUT domain.com/bookings
POST domain.com/bookings
DELETE domain.com/bookings

3) Only Two URL Per API

This is all about keeping things as simple as possible. A good API design will have just two possible URL such as:            domain.com/bookings
domain.com/bookings/999

So we would have:

GET domain.com/bookings – retrieves all bookings.

GET domain.com/bookings/999 – retrieves booking 999.

DELETE domain.com/bookings – deletes all bookings.

DELETE domain.com/bookings/999 – deletes booking 999.

Simple, no confusion on how to build the URL parameter and what it is used for.

4) Consider Using a Query String

Rather than building complex API URL, it is a better idea to use a quarry string. For example:

GET /salesman/12/bookings/11/zip/75080/city/jones/state/tx

Would be better achieved using the following query string:

GET /salesman/12/bookings/11?zip=75080&city=jones&state=tx

This makes the API call easier to understand if somebody has to pick it up and maintain it at a later date. We see quite clearly where the API URL stops and the actual search parameters begin if we do it this way.

Explore: 9 Best Automated API Testing Tools

Further Considerations

These are just a handful of best practice tips when it comes do designing REST API. But there are many more considerations. We have not touched on API output standardization including error reporting, and indeed we have not looked at error trapping at all. These and more need to be considered for standardization across all API within a specific project. Hopefully, the examples above have given you food for thought, so that you can begin making sensible API design decisions in the future.

Conclusion

Have a specific concern bothering you?

Try our complimentary 2-week POV engagement
I have read and accept the Privacy Policy
Our Latest Blogs
How to Choose the Right Software Testing Services for Your Business
Read More >
How Global Capability Centers(GCCs) Drive Growth for Enterprises?
Read More >
How to Build a Risk Management Platform for Payment Gateways Like Stripe [with example client case study]
Read More >

About The Author

Harsh Raval

Speak to our Experts
Lets Talk

Our Latest Blogs

November 28, 2024

How to Choose the Right Software Testing Services for Your Business

Read More →
November 28, 2024

How Global Capability Centers(GCCs) Drive Growth for Enterprises?

Read More →
November 28, 2024

How to Build a Risk Management Platform for Payment Gateways Like Stripe [with example client case study]

Read More →