'Techsplain' APIs like a Pro

4 min read

By Thilina Ashen Gamage

Business Value of APIs

As its name suggests, APIs (Application Programming Interfaces) are programmable access points used by applications to communicate with each other. In most business applications, APIs integrate heterogeneous systems —  to enhance the existing functionalities or create new features/products. This strategy brings in both time and cost savings for developers because instead of building everything from scratch, they can now easily leverage the capabilities of existing systems and focus on building core functionalities and experiences.

For instance, if you build a product like Uber or Airbnb today, its most critical features —  online maps and payments are already available as pre-built APIs provided by Google Maps and Stripe. After wiring them together, your product roadmap gets relatively shorter and more straightforward with other apparent benefits like faster time to market and economies of scale and expertise.

Not surprisingly, back in 2016, Gartner picked up this trend and declared that “we live in the API economy” in their famous “Welcome to the API Economy (2016)” article. Over the past years, by enabling new breeds of software business models, APIs, again and again, proved Marc Andreessen’s famous claim, “software is eating the world,” and today, almost every web application is using APIs in some way under the hood.

First, to lay our foundation on APIs, let’s understand how API communication happens.

API Communication Process

In tech literature, the API communication process is often compared to the food ordering process at restaurants, which include these three stages:

1. Accept orders (= requests to process/retrieve information) from customers (= which might be the client application),
2. Communicate to the kitchen -so the chefs can ‘process’ the food (= server application that handles backend services and process information), and
3. The waiter serves the food (= processed information) in return.

This model works well for both:

1. Customers who may not be interested in knowing about the cooking process (= client application that may not be interested in knowing the backend logic), and
2. Kitchens that may not want to expose their processes and secret recipes to the outsiders (= server application that may not want to expose its implementation details and critical data to the outsiders).

APIs are a great way to hide underlying implementation specifics of an application and provide a higher-level abstraction to the communication, making it more understandable by everyone.

Every restaurant provides a menu — listing all available food items offered by the kitchen with flavours, ingredients, and other information so that customers have all the information to make their orders. The API Specification does the same job in the API world by listing all available API endpoints offered by the server application with all message definitions and instructions to invoke them.

A good API Specification always follows industry standards, and this compliance helps us unify the API design and standardize data exchange between applications.

Classification of APIs

Like many things in tech, there is no one-size-fits-all design for APIs. However, based on the nature of communication, we can classify the most widely-used API types into three major categories as follows:

1 — On-Demand APIs (e.g. REST, GraphQL) allow the client to make requests for retrieving/processing information from the server.

Sample applications:

• Search queries
• Form submissions
• Data deletions & edits.

2 — Real-Time APIs (e.g. WebSocket APIs) allow both the server and the client to pass messages frequently at any given time.

Sample applications:

• IM/chat apps
• Push notifications
• Stock quotes
• Live score updates

3 — Event-Driven APIs (e.g. Webhook APIs) allow the server to push updates to the client based on event triggers (communication triggered by an event, just like a cue and a response).

• IM/chat apps
• Push notifications
• Stock quotes
• Live score updates

When you understand the basic behaviours of each API, you can tweak them to meet your exact requirement.

Key Takeaways

• APIs are programmable access points used for application-to-application communication.
• By connecting APIs, you can leverage the capabilities of multiple different systems to build new digital experiences.
• Using an API is like making an order at a restaurant.
  • The menu is the API Specification, and you have to refer to it and make the order- API request. The kitchen -the server application- will then process it and serve the food- processed information in return.
• The widely-used APIs can be classified into three types based on the nature of communication.
  • Use REST/GraphQL APIs for occasional, on-demand communication (takeaway/drive-through model).
  • Use WebSocket APIs for frequent, bi-directional communication (dine-In model ).
  • Use Webhook APIs for event-driven communication (home-delivery model).

In addition to these concepts, we can list many common characteristics between APIs and restaurants, for example:

• To design an efficient kitchen, you divide it into small units and streamline its processes (i.e. design the backend as small business units- microservices and streamline developer operations- DevOps)
• Handle peak orders by adding more staff and chefs (i.e. elastic load-balancing by adding more servers and backend resources)
• Strategies to provide great customer service (i.e. deliver a seamless API integration experience).

We will cover all these topics in-depth in the future until then, keep innovating!

Tools & References

• Diagrams and icons: diagrams.net, canva.com, flaticon.com, freepik.com, freeicons.io, icons8.com.