Modern API Design Paradigms (and When to Use Them)
The right API design is the one that makes your developers faster and your systems more maintainable.
👋 Hi, this is Thomas. Welcome to a new edition of Beyond Runtime, where I dive into the messy, fascinating world of distributed systems, debugging, AI, and system design. All through the lens of a CTO with 20+ years in the backend trenches.
QUOTE OF THE WEEK:
“Most of what we call "tech" is about getting the right information into a database and trying to prevent the wrong person from reading or updating it.” - Kelsey Hightower
APIs are the connective tissue of modern software systems. But not all APIs are created equal—and neither are the architectural styles behind them.
Today’s most widely used paradigms—REST, gRPC, GraphQL, and WebSockets—each come with their own philosophies, strengths, and trade-offs. Choosing between them isn’t just a technical decision; it reflects your product goals, team skills, and infrastructure priorities.
Let’s break them down.
🧱 REST: The Backbone of the Web
REST has been the dominant API style for nearly two decades. And for good reason. It’s simple, well-understood, and fits naturally into the web’s HTTP fabric.
REST APIs expose resources (like /users or /orders) and let clients interact with them using standard HTTP methods (GET, POST, PUT, DELETE). They're stateless, cache-friendly, and incredibly easy to work with across languages and platforms.
When REST shines:
You want wide compatibility with browsers, mobile apps, and IoT devices
Your team values quick implementation and easy debugging
You’re building standard CRUD-style operations over well-defined resources
You don’t need fine-grained queries or real-time updates
But beware: REST’s simplicity can come at a cost. For example, if a mobile app only needs a user’s name and avatar, but the /users endpoint returns the full user profile, you’re sending more data than needed. Overfetching and underfetching are common issues, and that’s where other paradigms step in.
🧬 GraphQL: Flexible Queries for Complex Needs
GraphQL, originally built by Facebook, flips REST on its head. Instead of multiple endpoints, you get a single endpoint that clients query for exactly the data they need.
The shape of the response matches the query, whether you want a list of users, their most recent posts, and each post’s comments. This is especially useful in mobile and frontend-heavy apps where minimizing payload size and reducing roundtrips is crucial.
Where GraphQL excels:
Your frontend developers need precise, flexible data access
You’re aggregating data from multiple services or databases
Your app has deeply nested or relational data structures
You want to reduce overfetching and underfetching in client queries
Things to consider: GraphQL’s magic isn’t “free.” Behind the scenes, GraphQL servers may run multiple resolver functions per field, leading to performance pitfalls if not carefully managed. Also, debugging queries can be trickier, and it’s overkill for simpler applications with fixed data structures.
⚡ gRPC: Speed and Type Safety for Microservices
gRPC is Google’s high-performance, strongly typed RPC framework. It uses HTTP/2 and Protocol Buffers to enable lightning-fast, low-overhead communication between services and it’s especially useful inside microservices architectures.
Rather than modeling resources like REST, gRPC defines service contracts using .proto files, generating client and server code automatically.
When to reach for gRPC:
You’re building internal APIs between microservices
You need fast, compact communication at scale
You want strong typing and schema enforcement
You’re comfortable with Protocol Buffers and want code generation
Gotchas: gRPC’s learning curve is steeper than REST or GraphQL. Protocol Buffers are efficient but not human-readable, and debugging can be a bit more painful. Plus, it’s not natively supported in browsers without extra tooling (e.g. gRPC-Web), so don’t expect it to replace your public APIs any time soon.
🔁 WebSockets: Persistent Connections for Real-Time Apps
While REST and GraphQL are request-response models, WebSockets enable persistent, full-duplex communication. Think live sports scores, chat apps, multiplayer games, or IoT systems streaming telemetry.
WebSockets keep a single open connection between client and server, so you can push data instantly without polling.
Perfect for:
Real-time apps with continuous updates
Bidirectional communication (e.g., chat, games)
Low-latency environments like trading or logistics
Smart devices and sensor networks
Trade-offs: WebSockets are stateful and resource-intensive. Each connection uses memory, and scaling horizontally requires careful orchestration (think distributed state management and load balancers that support sticky sessions). They’re incredibly powerful—just make sure your infrastructure is ready.
How to Choose the Right API Style
There’s no one-size-fits-all answer, but asking the right questions helps:
Are your clients web apps, mobile devices, or internal services?
Do you need real-time updates or low latency?
Are you serving structured resources or complex, nested data?
Do your engineers prefer type safety and code generation?
How familiar is your team with the tooling and trade-offs?
Sometimes, the answer isn’t either/or. Many modern systems use multiple paradigms in parallel. REST for public APIs, gRPC between services, GraphQL for frontend queries, and WebSockets for real-time features.
💜 This newsletter is sponsored by Multiplayer.app. AI-powered debugging for distributed systems.
I originally dived deep into API architectures here:
I explored these topics:
Five essential API architecture components
Four popular API architecture styles
Eight API architecture best practices
📚 Interesting Articles & Resources
Over the years, I’ve spent far too much time reverse-engineering systems no one fully understands anymore. That’s why I’m hosting a webinar where I dig into:
❓ How modern systems outgrew our old tooling
❓ Where AI can help engineers save hours of debugging and system documentation grunt work
❓ And why embedding context into your workflows is key to building resilient systems
If you’ve ever had to “guess and grep” your way through a bug… this webinar is for you.
📅 Tue, May 20th 2:00PM EDT 🔗 Register here: https://my.demio.com/ref/L741ubiIpy79IcJ9
[29 MAY 2025 EDIT] If you missed this webinar you can catch up here:
I love how you emphasize that picking an API style is just as much about team skills and product goals as it is about tech specs!