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:
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.
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
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.
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
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.
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)