Learn

👨‍🏫 A Practical Guide to 6 API Patterns

Let’s start with the classic question: How technical does a TPM need to be?

There are many, many ways to answer that question. But regardless of which answer you’re given, understanding APIs is a fundamental slice of system design that establishes your Technical Versatility.

Modern system design without APIs?

Without APIs, system design would be chaotic and inefficient. It would essentially cease to exist!

Each application would need custom code to communicate with every other application. This lack of standardization would lead to a tangled web of integrations, making maintenance and scalability nearly impossible. Can you imagine?? Every single piece of common and popular software we know today wouldn’t exist.

To be honest, it is quite impossible to consider our modern world without APIs.

(Take a moment to say thank you to your APIs today!)

The Top 6 API Patterns

When I first learned about APIs, this was the analogy I was introduced to:

This analogy is fantastic! But, as your understanding of system design progresses, it falls short of capturing the nuances of the many API patterns.

Let’s walk through the patterns from a chronological perspective, starting in the late 90’s.

1998: SOAP (Simple Object Access Protocol)

Rewind to 1998, right before the dot-com bubble. SOAP is one of the oldest and most established API protocols, designed for secure and reliable communication.

• A helpful analogy: Imagine a mail carrier (SOAP) who delivers letters (messages) between houses (applications). The mail carrier has to make sure every letter has a stamp, address, and return address in the correct places, SOAP makes sure that every message follows a strict format. This ensures that the messages are understood correctly by the receiving application.

• When is it used: SOAP remains vital in secure, transaction-heavy environments like online banking and enterprise services.

• Pros: Strong security, standardized format, reliable.

• Cons: Can be complex and slow, uses a lot of bandwidth.

2000: REST (Representational State Transfer)

Now let’s go right to the turn of the century. The year is 2000. The dot-com bubble is upon us! The web is exploding. We need a better way of managing web communications. REST is the most widely used API pattern due to its simplicity and scalability.

• A helpful analogy: When you order pizza online, you don’t need to know how the pizza is made or how it gets to you. You just click buttons to choose what you want. Similarly, with REST, you make requests to a server and get back exactly what you asked for, like a pizza being delivered to your house.

• When is it used: You probably use a REST API every day. Websites, mobile applications such as social media platforms and e-commerce sites all use REST to some extent.

• Pros: Easy to use, lightweight, widely supported

• Cons: Limited to HTTP, stateless nature can be a drawback in some scenarios.

I spent a lot of time with REST APIs when I was an API engineer at ExxonMobil. They were a huge enabler to faster business operations and collaboration across data analyst groups.

2007: Webhooks

As web and mobile apps required real-time communications, Webhooks were introduced. The term was coined in 2007. These are event-driven mechanisms that have helped establish basic things we’re familiar with today, like simple notifications.

• A helpful analogy: An alarm clock goes off at the right time to wake you up without you needing to watch the clock. Similarly, a Webhook sends a notification to your application whenever a specific event happens, so you don’t need to keep checking if the event has occurred.

• When is it used: Webhooks trigger specific actions across different systems: event-driven services like payment processing notifications or continuous integration/continuous deployment (CI/CD) pipelines.

• Pros: Simple, real-time notifications, no need for constant polling.

• Cons: Can be less secure, depends on external services.

2011: Web Socket

WebSockets enable real-time, bi-directional communication between a client and server over a single, long-lived connection. They are fundamental to fast communication across systems.

• A helpful analogy: Imagine two friends on a phone call, where they can talk to each other instantly and continuously without hanging up. They can constantly talk with and respond to one another. WebSocket keeps a constant connection open between two applications so they can send messages back and forth instantly, just like friends chatting on the phone.

• When is it used: Event-driven services like payment processing notifications. Continuous integration/continuous deployment (CI/CD) pipelines.

• Pros: Real-time, bi-directional communication, low latency.

• Cons: Not suitable for all types of applications, complexity in scaling.

February 2015: gRPC

Moving into 2015, modern system design really picks up speed in maturing. The modern, large scale, distributed systems demand something more efficient.

GRPC was developed by Google and released publicly in February 2015. They are designed for high-performance, scalable API communication, particularly useful in microservices architectures. I personally didn’t have much exposure to these until my time at Twitter with the vast distributed, scalable systems we were running there for the social network and the ad-stack.

• A helpful analogy: Imagine gRPC as a dedicated phone line between two offices with operators who speak the same specialized language (Protocol Buffers). This setup allows them to communicate faster and more efficiently than using regular mail (HTTP REST calls), where letters must be written, sent, received, and read, often leading to delays and misunderstandings.

• When is it used: Microservices architectures, real-time communication services, and systems requiring efficient, high-performance data exchange.

• Pros: High performance, supports multiple languages, efficient

• Cons: More complex setup, extra overhead for smaller apps, strict contract

July 2015: GraphQL

Around the same time gRPC was introduced, GraphQL was released and it rapidly gained traction, especially among developers dealing with complex data requirements. It is often considered the 2nd most popular (after REST) API pattern. Companies like Facebook, GitHub, and Airbnb have adopted GraphQL.

• A helpful analogy: Imagine a buffet (GraphQL) where you can pick exactly what you want on your plate instead of ordering a fixed menu. You don’t have to take a full meal; you can just take the foods you like. With GraphQL, instead of getting all the data you might not need, you can request just the specific pieces of data you want, saving time and making things more efficient.

• When is it used: Applications needing specific data from large datasets or real-time applications like social media feeds.

• Pros: Flexible data retrieval, single endpoint, strongly typed schema

• Cons: Security concerns, potential overuse of resources (ie easy to allow excessive queries), steeper learning curve

Recap

Whew. That was a lot.

For me, it’s interesting to look at the chronological development of these patterns rather than a static list of patterns. By looking through the lens of time, you can start to see a shadow of how system design in general has evolved.

Now a quick summary:

• SOAP (Simple Object Access Protocol) - Introduced in 1998, SOAP is one of the oldest and most established API protocols, designed for secure and reliable communication.

• REST (Representational State Transfer) - Developed in 2000, REST has become the most widely used API pattern due to its simplicity and scalability.

• Webhook - The name was officially coined in 2007 but developed in the few years prior, Webhooks enable event-driven automated tiggers happening in real time.

• WebSocket - Introduced in 2011, WebSockets enable real-time, bi-directional communication between a client and server over a single, long-lived connection.

• gRPC (gRPC Remote Procedure Call) - Released in 2015 by Google, gRPC is designed for high-performance, scalable API communication, particularly useful in microservices architectures.

• GraphQL - Introduced by Facebook in 2015, GraphQL is a major API pattern known for its flexibility in querying data.

A note on Technical Versatility…

I’ll be honest, I learned a thing or two preparing this post. For example, I don’t have much experience with Webhooks. But after writing this, I’m better equipped to talk through Webhooks scenarios.

Pro-tip: The most important part of your Technical Versatility is your willingness and eagerness to learn.

A word from today’s Sponsor.

Simple Skincare for Smart Investors

You're already investing your money wisely, so why not invest in yourself too? Tiege Hanley’s Bare Minimum Routine offers an affordable, high-quality solution for men who want to look and feel their best. For only $9, you get a simple, effective skincare system that includes a face wash and an AM moisturizer with SPF to keep your face hydrated and protected all day long.

Do the bare minimum, order your set today.

People

🤝 Naveen Chandrawanshi, Top Programming Voice

I’ll be honest, I don’t know Naveen personally. But his posts are highly visual and anchored on system design. I often enjoy how he visualizes complex topics. Below is one of this posts I found insightful!

Resources

📚 The Pragmatic Engineer

I don’t know if this newsletter even needs an introduction. It has grown so rapidly in popularity in the past few years, it’s hard to believe.

Gergely Orosz is a fantastic writer and has created an incredibly high-value newsletter for anyone in the tech industry. There are some free posts, but most paid posts.

A couple years ago I contributed to one of his articles focused on the role of Technical Program Managers. Check it out!