Understanding Web API basics Through Analogies
The world works on analogies. From the lyrics of the songs to visionary talks. Then why don’t we use analogies for seemingly difficult…
The world works on analogies. From the lyrics of the songs to visionary talks. Then why don’t we use analogies for seemingly difficult subject matter for “perceived non-technical” folks so they are able to comprehend simple “technical” terms. I mean, in this day and age, are we still debating if we are technical or non-technical?
At The Creators Devhub, one of our goals is to help bridge the understanding gap between businesses and the technologies that they are making use of. That’s why I picked up Web APIs as the topic for this series. Businesses offering products and services via their platforms are all making use of the Web APIs. In fact, anyone interacting with the Web since the past two decades, is consuming some form of this concept.
Earlier this year, I gave an API 101 workshop for undergraduate students participating at a hackathon. While preparing for the workshop, my biggest challenge was “how can I simplify the content enough for the students, who have just begun their coding journeys, so that they would be intrigued enough to dig into it further by themselves?”. So I dug into some real world analogies that would fit the API narrative. I am sharing that in this article with you.
The intention of putting this blog together is to convey a basic understanding of the concept of APIs and web APIs to a wider audience:
Students taking off their web software development journeys
Technology professionals involved in software product development
Technical sales teams involved with digital products and conveying the story of digital transformation
Anybody else who would like to understand about APIs
An intro: Application Programming Interfaces
Before we jump to the analogies, let’s take a dig at the words in the acronym API. As the name suggests, it has three defining components. An application programming interface is an interface that is used by programs to interact with an application. Read that again.
An interface can be considered as a connector that is following a set of rules. The rules for the connector are usually determined by the source or the provider of the utility.
A program which interacts with the interface can be considered as an entity following a set of coded instructions to connect with the interface and consume the resource that is returned. It could be either a human user who can do limited operations with, say a gaming controller, or it could be a software program consuming instructions on how to use another software program.
The application is a utility or a service being consumed. Every utility has a producer or a provider for it. Hence, enter the consumer-producer model of APIs. The provider of the utility is usually the one providing the recommended steps to interface with the application, in the form of a documented contract, i.e., an API document.
In other words, we can also define an API as an interface which supports interoperability of some useful information between two parties.
The Analogies
Analogy 01: Restaurant
The process of ordering a meal at a restaurant and getting it delivered can be well related with how an API works. Refer the below flow:
There is an individual who wants to dine-in at a restaurant.
There are several dining options but she chooses to go to restaurant X. There could be many reasons for choosing to go to restaurant X. She made the decision primarily based on food quality reviews and because the restaurant has cleared food safety audits regularly.
The customer is presented with a menu card consisting of a list of food items that are offered by the restaurant.
There is a server who accepts the order from the customer and takes it to the kitchen. There are more than one server at the restaurant.
The requested items are prepared in the kitchen and sent to the customer via the server acting as a messenger. The customer consumes the food item.
Since it was an a-la-carte menu, the customer pays only for the food items (utility) consumed. If it were a buffet, the customer would have paid a fixed upfront price and consumed as many items listed out on the buffet. There is also a service fee that is added to the bill. This service fee is added as a result of using restaurant space, the service provided by the servers who acted as a messenger between the customer and the kitchen.
Let’s see another analogy.
Analogy 02: An electric outlet
For illustration of this analogy, let’s use the example of keyed outlets that we use on a daily basis for charging our electronic devices.
An electric outlet socket is an interface for plugging in an electric device in order to charge it or provide it with a continuous electric supply.
The electricity is supplied from a power plant via insulated transmission wires, most likely built of copper and aluminium. Power plants are either privately owned or government owned and the electricity is distributed by various companies.
The consumer of the interface, even though it may seem like a human who wants to charge their electronic appliance, but it’s actually the electric appliance itself that is going to consume the electricity.
The program to interface with the electric outlet is in the form of a plug configuration of the device. The device plug will fit into the electric outlet only if their configuration matches. Example, a plug configuration of Type B cannot fit into a Type D electric outlet.
Enter globalization. We all travel the world now and we have so many electronics on us, phone, laptop, camera, even drones. Most of us travellers keep an adaptor. It could be specific to the country we are visiting to-and-from, like Canada-India Type B to Type D adapter, or a universal adapter with multiple socket configurations. I had to buy one when I visited Europe.
There could be more than one supply endpoints, ie. electricity outlets, located in a building facility. They may be lower voltage supplies for charging regular devices, or a higher voltage outlet supplying electricity to a cooking range.
The safety standards of electric sockets and plugs are laid out by the International Electrotechnical Commission and are followed by countries and companies while building out the interfaces.
The payment for electricity (utility) consumption is done by the owner of the housing facility where the electric interface is installed. The electric companies may provide a postpaid and/or a pre-paid option for paying for electricity consumption. There may be an added interface installation fee. Since the plug-outlet model is an age-old method of electricity consumption, the facility owners usually do not charge for using the interface, but only for consuming the electricity exposed through the interface.
Analogy 03: A computer game — Tetris — No internet
Almost every one of us, growing up in the 80s or 90s, would have played a game of Tetris on their handheld gaming console or a desktop computer. Did it operate with the same concept of an API? Kind of. For the purpose of this analogy, let’s take the example of a Tetris game on a desktop computer.
A game is a software used as an entertainment utility installed on a computing device.
The gaming software Tetris could be part of the operating system (OS) software package provided by the OS provider or it could be a software written by another company and installed separately on the computer system.
The consumer of the game-as-a-utility is a human. Though the human interacts with the game via an input device and receives the output of interaction via a monitor display.
The interface for the user is the keyboard keystrokes or mouse clicks. The human user types keys following instructions in the game rulebook. Each keystroke calls an instruction which is channeled by different system buses within the computer architecture, triggers the gaming software and transmits the outcome back via the different system buses to the display device where the outcome of gameplay is reflected. Does this also generically say that each keystroke input that results into a response via the computer display screen is a form of communication that can be considered similar to a communication via the APIs? Sure.
The security of the gaming software can be measured if the software contains any malware or is a corrupted file. If the gaming software is licensed, it can be guaranteed that the software file would not be corrupted and would not contain any malware. If the hosting computer machine is being regularly scanned for computer viruses, that would also ensure that the gaming software file will be safe to use.
The pricing of the game may be included in the pricing of the OS license purchased or the game purchased separately. Game-as-a-utility may be available for free as well.
Key Inferences
Some important inferences we can take out from the analogies are
1. An API always exposes something of value, a utility. Food, electricity, and gaming software are all utilities. Since there is some value being exposed, there may be a price associated with the utility.
2. There is an owner/provider of the utility exposed by an API. Think restaurant, power plant, OS producer.
3. There will always be an intended consumer for whom the utility is being produced. Think, a hungry human, an electronic device, a human user consuming entertainment through a computing device.
4. The program consuming or interfacing with the API, must follow interfacing instructions provided by the API provider.
a). One restaurant’s menu card will not work in another restaurant.
b). A Type B plug configuration will not work with a Type D configuration.
c). Even though the Tetris game has universal rules, the producer controls what input instruction will trigger the Tetris to move in a certain way.
** Similar to an adapter for different plug configurations, there are now platforms that provide you with different options for restaurants by your food choice. Still a menu card of one restaurant can not be used in another. We will dig into this in another article when talking about the productization of APIs and the concept of plug and play models.
5. The API may expose different variations of the utility, also called the endpoints. Think about a restaurant having a breakfast menu, a dinner menu, a cocktail menu and a dessert menu. Think about different voltage outlets for electricity but electricity is supplied by the same power plant.
6. The exchange of instructions is a set of request-response and is carried out via a communication channel. A server as a messenger, insulated copper/aluminium wires, an instruction to the machine converted into binary bits, carried out through system buses, processed and reconverted into human understandable instruction on the screen, are all examples of communication channels.
7. Any utility derives its value from it’s resourcefulness, usability and safety. Food quality & safety audits, safety standards for electric appliances, a valid licence on gaming software and regular software scans for viruses ensures provider-consumer safety.
8. The use and consumption of the utility through an API may or may not be priced depending on the provider.
Enter the Web APIs
The World Wide Web (www), also known as the Web, has seen many transformations since its beginning. As the Internet provided us a way to communicate between different computing nodes laid out at far off geographical distances (i.e., the how of communication), there had to be an environment or layout for “what the communication would look like”, and that emerged to be the Web.
The earliest version, also known as the Web 1.0, was heavily based on static information sharing. With the changes in the communication styles, the Web evolved transitioning into Web 2.0, a term popularized by Tim O’Reilly as he called for “harnessing of collective intelligence” via the Web, hence giving way to more user generated data and emergence of the social web. At its core was the principle of interoperability. This is the phase when the concept of Web API was coined. The Web API of the social web exposed utilities in the form of services and resources, and provided instructions for the consumer on how to consume the resource.
Over the years, the Web has also seen many different ways of consumption of Web APIs. These are not necessarily considered as transformations, but different available styles of communicating between two software programs. The description of each style is out of scope of this article but here they are briefly. Remote Procedure Calls (RPC) is the oldest version, where the request made by the client for a service is executed on a remote server. It is further broken down into different specifications XML-RPC, JSON-RPC, SOAP, gRPC, where gRPC being the newest introduced style. Both SOAP and gRPC are in heavy use even today. The Representational State Transfer (REST) is one of the most popular ways to build out communication between software programs and has been around since early 2000s. GraphQL is another newer version developed by Facebook internally in 2012 and then released for public use in 2015. For further reading on differences between these styles, please refer to the resources I have pasted at the end of this article.
Since we concluded some key inferences from the analogies above, let’s see with an example how they correspond to the Web APIs. For this illustration, we will use the Twilio Voice API as a model.
Twilio Voice API is a product of Twilio (a cloud communications platform as a service used by the likes of Uber, Lyft, AirBnb, Zendesk) that allows someone to make, receive, and monitor calls around the world.
Inference 01: A utility or service offering
Internet based voice calls.
Inference 02: Provider
Twilio Inc.
Inference 03: Consumer
A program written by a software developer building an application. The service in its full connected form, is then consumed by the users of the application.
Inference 04: API document
A reference guide for “how” the consumer should interface with the service and what is expected as a response to each call made via the interface. https://www.twilio.com/docs/voice/api
Inference 05: Endpoints
The service may have several endpoints, i.e., different operations you can perform on the service. Ex: create a call, make an outgoing call, modify ongoing calls, query data about calls, create conference calls, call recordings and more.
Inference 06: Request-response and communication channel
Every request-for-data initiated on an API endpoint is expected to receive a response. The Web APIs generally make use of HTTP, HyperText Transfer Protocol, a commonly used web protocol to define the format of messages to be transmitted and provide information on the action required by the receiver. Twilio makes use of the RESTful architecture style for APIs and uses HTTP. The returned message for Twilio APIs is in a JSON format (a data notation).
Inference 07: Security
Communication between Twilio API and the web application is encrypted. Twilio supports the TLS cryptographic protocol. Supports HTTP basic and digest authentication.
Inference 08: Pricing
Usage based pricing.
So now you know, Web APIs are just another way of communication. Its initial consumer is a software program written by a software developer to use the exposed service utility as part of a much bigger software application.
Here are some resources for further reading:
This blog is the first of the 3-part series to understand Web APIs. Next we will jump into understanding the Evolution of the web and the productization of Web APIs.
Please feel free to leave your feedback in the comments below.