API: The Convenience Store Clerk of Software

Difficulty: Easy

Do you recognize this friendly face? Apu from the Simpsons, can teach us a lot about a a profoundly important construct in the software world, the Application Programming Interface (API). APIs are found in virtually every software program, and they are responsible for delivering a significant portion of application functionality, especially it today’s world where many applications are distributed and function on the World Wide Web. So how can Apu help us understand what an API is? Even though Apu graduated top of his class of 7,000,000 in Computer Science at Calcutta Technical Institute and holds a PhD from Springfield Heights Institute of Technology, his grounding job responsibilities at the Kwik-e-Mart are what really can teach us about the working characteristics of an API.

So what is an API? Wikipedia says it’s a set of subroutine definitions, protocols, and tools for building application software. This is somewhat ambiguous, but not to worry, Apu can help us understand more about what exactly this means. Apu’s job functions and interactions behind the counter (interface) at the Kwik-e-Mart mirror the functions and characteristics of an API.

If I had to simplify the job function of an API, I’d say that it is the software equivalent of someone who provides a service. Apu provides several services to his customers, just as APIs provide services to its “customers” (which happen to be software programs). It is the means by which these services are provided that the “set of subroutine definitions, protocols, and tools for building application software” are applied. I’m going to break-down this definition of the API into the three separate categories, covering subroutine definitions, protocols, and tools separately.

Subroutine Definitions

Let’s first take a look at subroutine definitions, which are basically a set of instructions that, when followed, provide a service. In Apu’s case, for example, these definitions are the instructions on how to grab a pack of cigarettes from the shelf, or ring-up the total bill of purchased items. For getting the cigarettes, Apu’s subroutine may look like this:

  1. Request identification from customer.
  2. Confirm that customer is above 18.
  3. If below 18, respectfully deny purchase of the cigarettes.
  4. If 18 or above, walk to the shelf behind the counter.
  5. Pull desired cigarettes from the shelf.
  6. Walk back to the counter, and place cigarettes down.
  7. Proceed to the ring-up subroutine.

Subroutine definitions, like the one above, lay the groundwork for specifying how an API will actually know how to provide the service. These definitions can actually involve the use of other subroutines as the building blocks to create intricate, more complicated service offerings. For Apu, his “clean the store” subroutine may involve the “sweep the floor,” “wash the windows,” and “turn off lights” subroutines.

Protocols

Next-up is the protocols. Protocols are essentially a set of rules that must be followed in order to interact with the API. In Apu’s case, the protocols that must be followed include, (but certainly not limited to):

  • All alcohol must be purchased by a client over the age of 21 with valid ID.
  • All tobacco must be purchased by a client over the age of 18 with valid ID.
  • All clients must speak in either English or Hindi in order for requests to be understood.
  • All payments must be made with currency in USD.
  • To order a hotdog, say something along the lines of, “May I please have a hotdog.”

These rules help customers understand how to get the services they desire at the Kwik-e-Mart. If customers wants to purchase alcohol, they better be over 21 and bring their current photo IDs. In the software world, it is important for developers, who want to use an API, to understand exactly how to interact with it; the protocols of the API provide that information to the developer. With software, these protocols are usually specified in documentation that is provided by the developer that made the API. As an example, you can find the Twitter API documentation here. If you go to that page, you’ll see that there is information regarding how to authenticate (“login”), what rules apply for rate limiting (how much and how often you can ask for services from the API), and client policies, which put restrictions on the usage of the API. For the Apu API, we have restrictions on the sale of alcohol and tobacco, but we also have the rules for how to actually initiate the subroutines defined in the API. To kick-off the “get hotdog” subroutine, the customer first has to ask Apu, “May I please have a hotdog.” This protocol would clearly be defined in the Apu API documentation (if it was maintained by the developer appropriately).

Tools

Finally, we have tools. This is probably the easiest facet of the API definition to understand, and it probably doesn’t even need an analogy. (I’m going to give one anyway.) In order for Apu to facilitate his job successfully, he employs the use of tools to complete the services that he provides. To get a hotdog from the hotdog roller, he might need to use gloves and a pair of tongs. To get something off the top shelf behind the counter, he may need to use a step-ladder. To ring-up a customer, Apu needs to use a cash register to store the money and calculate the total cost of purchases. The tongs, step-ladder, and cash register are examples of the tools used in the Apu API. In the software world, tools typically mean other pieces of software or hardware. For developers, rather than re-inventing the wheel for certain tasks, they may choose to use software that was written by someone else, perhaps to send an email, display a map, or play a video. These tools assist the API on successfully providing its services.

Conclusion

The combination of subroutine definitions, protocols, and tools result in a functioning API. All-in-all, APIs are programs, or bits of programs, that provide some kind of service. The service offerings are facilitated by receiving a request from a software client (customer), using the subroutine definitions and tools to execute the service, and then providing a response back to the client or customer. For the Apu API, this response is almost always, “Thank you, come again!”