Real World APIs

We use APIs in some form or another without realizing it. The “Application” part of API doesn’t have to mean “computer only.” Imagine ordering at your local drive-through window. The details of how your burger, fries, and drink get into your hands are unimportant and hidden from you by the walls of the building. Think of these as backend operations like a database query. When you approach the window, you see the API promotion as a menu – a list of choices (or operations) that your fast food joint allows. So when you say “Give me a large #1 with mayo and a Coke,” where the #1 is documented as a single patty cheeseburger with a tomato, lettuce, and pickles, you have just used the customer API for ordering. How could this look as a REST call? http://www.fastfood.com/orderSpecial?number=1&size=large&drink=coke&extras=mayo where extras is an optional argument; in other words if you don’t want extras, you don’t specify the extras argument. What you get back is a package of stuff as the response to your request. In this real world case the “response” is your burger with mayo, a large order of fries, and a large Coke.

This is a pretty simple example but emphasizes some characteristics of a good API. It’s self-documenting – the operation name clearly states its use and the options are well defined and unambiguous. Any unknowns are resolved with a picture and textual descriptions of what the #1 actually is. It’s all a matter of good documentation which will reduce service calls to your organization and not confuse users. Since the response is what you expected, the API adheres to the principle of least astonishment. Sticking to this will keep user frustration low and increase adoption of the API. The call to order a special is likely a method of convenience, or a wrapper, which allows you to perform a single high level function composed of individual pieces. Providing this kind of abstraction is good practice; imagine the annoyance of making three or four separate calls and then having to build the special ourselves! Of course, there are certainly supported use cases in which someone can order a drink or just order fries. Speaking of which, under the hood the call /orderSpecial probably calls other parts of the API such as /orderDrink and /orderFries. This is a good example of reusability and allows for fast response to changes in the underlying implementation of the API.

In a series of upcoming articles, we will explore APIs in the wild. We’ll take a look at how enterprises can conquer the challenges of API creation, deployment, promotion, security, maintenance and administration, and monitoring.