Misconception in Web API Design
Since the inception of API program a few years back (geeze it's been that long!?) there was (and still is) a common belief that Web APIs should (in some rare cases it was even a must) conform to the constraints of the REST architecture style. We will discuss and discover in this article that this a misconception and a major trap for every API program.
To be honest, I am not an active software developer (anymore) and I don't want to go into the nutty details of REST architecture style. However, I do want to emphasize on the fact that an API program may deviate on a major detour if the program itself does not properly and reasonable apply RESTful principles to its Web API architecture and design principles.
As mentioned in my previous articles, a Web API is all about solving a customer problem. A well-designed Web API should primarily address the goals of the consumer app. The hard lesson we learned (mental note - failure is good) is that API developers should always prime their design on business requirements rather than technical elegance or REST compliancy (or any other de-facto standard). In fact, it does not matter whether an interface is strictly “RESTful”, so long as it does the job it has be designed to do. In other words, REST most certainly is not a necessary condition for a successful Web API. Hence the following logical expression is not true:
If REST, then "Web API"
By focusing too much on technical aspects and standard conformity, the Web API designer's focus is not where it should be - on the consumer and his real-world business problem. With a bit of tongue in a cheek, we put REST to peace. Not entirely six foot under but just out of sight.
But if REST is not the holy grail of Web API design, what is it then?
The good news is that there are established concepts and methods readily available today to make a great Web API. Product managers and designer in every industry understand that focusing on how their product will be used is a key step in building products that consumers want. By taking a user-centric approach, designers of mobile devices and successful social media applications such as Twitter and Facebook have massively increased the popularity of their products. This focus on usability is central to good API design. Which brings us to the second important question:
Who exactly is the customer of a Web API?
While traditional product designers focus on the user experience (UX), an API designer strives to improve the developer experience (DX). Software engineers and application developers must be able to easily consume the functionality an API exposes if that API aspires to be truly valuable to the Web and mobile application. Amongst several strategies and solutions that can be used to make great Web APIs, a best practice and general rule of thumb is that API designers try to create their interface designs from the perspective of their target developers, adding REST more like a spice to an already fine meal.
Conclusion
Shifting the focus of API design from technical aspects (i.e REST) to the business context in which that API will be consumed inevitably will improve the experience of using it.
Improving a Web APIs usability will result in higher adoption rates and lower integration costs – both of which are important goals for any API program.
