Best Practices for REST API Design
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.
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.
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/bookingsAnd then every post type makes sense:GET domain.com/bookingsPUT domain.com/bookingsPOST domain.com/bookingsDELETE domain.com/bookings
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/999So we would have:GET domain.com/bookings – retrieves all bookings.GET domain.com/bookings/999 – retrieves booking 999.And: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.
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/txWould be better achieved using the following query string:GET /salesman/12/bookings/11?zip=75080&city=jones&state=txThis 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.
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.
Everything you need to know about outsourcing technology developmentAccess a special Introduction Package with everything you want to know about outsourcing your technology development. How should you evaluate a partner? What components of your solution that are suitable to be handed off to a partner? These answers and more below.