What Is an API Paradigm?

An API paradigm defines how your API exposes data and behavior to the outside world.

It answers questions like:

• How do clients request data?

• How is data structured?

• How flexible is querying?

• Who controls the shape of responses?

Think of it as the grammar of your API—it dictates how developers “talk” to your system.

Why This Decision Matters (A Lot)

Here’s the part many teams underestimate:

Once developers start using your API, changing it is extremely difficult—sometimes impossible.

That means:

• You can’t casually switch paradigms later

• You can’t redesign without breaking clients

• You’re committing long-term

So yeah… this isn’t a “we’ll refactor later” situation.

The Two Big Categories of APIs

Chapter 2 groups APIs into two high-level models:

1. Request–Response APIs

The classic model:

• Client sends a request

• Server returns a response

This is the foundation of most APIs today.

2. Event-Driven APIs

A more modern approach:

• Systems react to events

• Communication is asynchronous

Instead of asking:

“Give me data”

You’re saying:

“Tell me when something happens”

We’ll break both down.

Part 1: Request–Response APIs

This is where most developers live.

These APIs typically:

• Use HTTP

• Return JSON or XML

• Expose endpoints

There are three major paradigms here:

1. REST (Representational State Transfer)

The default choice for most teams—and for good reason.

Core Idea:

Everything is a resource.

Example:

/users
/users/123

Key Principles:

• Use nouns, not verbs

• Use HTTP methods:

  • GET → read

  • POST → create

  • PUT/PATCH → update

  • DELETE → remove

Why REST Works

• Simple and intuitive

• Widely adopted

• Easy to cache

• Works well with HTTP

It’s the “safe choice”—like ordering chicken at a restaurant. Hard to mess up.

Where REST Struggles

• Over-fetching (too much data)

• Under-fetching (too many requests)

• Rigid response structures

You get what the server gives you… even if you don’t need half of it.

2. RPC (Remote Procedure Call)

Core Idea:

Call functions remotely like they’re local.

Example:

/getUser
/createOrder

Instead of resources, you expose actions.

Why RPC Works

• Straightforward mental model

• Great for internal services

• Easier to map to backend logic

Where RPC Struggles

• Can become inconsistent quickly

• Harder to standardize

• Less aligned with HTTP semantics

It’s fast and flexible… until it becomes chaos.

3. GraphQL

The “modern” approach.

Core Idea:

Let the client decide what data it wants.

Example:

{
  user(id: 123) {
    name
    email
  }
}

Why GraphQL Works

• No over-fetching

• No under-fetching

• Highly flexible queries

• Strong typing

Clients get exactly what they ask for—nothing more, nothing less.

Where GraphQL Struggles

• More complex backend

• Harder caching

• Performance can be tricky

• Debugging is… fun 😅

The flexibility is powerful—but comes with responsibility.

Part 2: Event-Driven APIs

Now we shift from:

“Request → Response”

to:

“Something happened → React”

Core Idea

Instead of polling for updates, systems emit events.

Examples:

• “Payment completed”

• “User signed up”

• “Order shipped”

Other systems subscribe and react.

Common Patterns

Webhooks

• Server sends HTTP requests when events occur

• Simple and widely used

Example:

Stripe tells your app: “Payment successful”

WebSockets

• Persistent connection

• Real-time communication

Used for:

• Chat apps

• Live dashboards

• Multiplayer games

Why Event-Driven APIs Matter

• Real-time updates

• Reduced polling

• Better scalability for async workflows

Trade-offs

• Harder to debug

• Event ordering issues

• Reliability concerns (missed events, retries)

Basically:

Great power, great complexity.

Choosing the Right Paradigm

Here’s the reality:

There is no “best” API paradigm—only the best fit for your use case.

Chapter 2 emphasizes:

• Your product requirements should drive your choice

• Not hype, trends, or what Twitter says this week

Quick Decision Guide

• REST → Public APIs, simplicity, standardization

• RPC → Internal services, speed, direct control

• GraphQL → Complex frontends, flexible data needs

• Event-driven → Real-time systems, async workflows

The Real Lesson of Chapter 2

This chapter isn’t just about paradigms—it’s about intentional design.

Too many teams:

• Pick REST because “everyone uses it”

• Jump to GraphQL because it’s trendy

• Mix paradigms without strategy

And then wonder why things get messy.

Final Thoughts

Chapter 2 teaches one critical mindset:

Your API design is a long-term contract with developers.

Choose your paradigm based on:

• Your users

• Your use cases

• Your system constraints

Not hype.

Because once your API is out in the wild?

Changing it is like changing a plane engine mid-flight—while users are still onboard.