Types of APIs: REST, GraphQL, SOAP, and Beyond

Now that you understand what an API is, let us explore the different styles of APIs that exist. Not all APIs are the same. Over the decades, engineers have developed multiple architectural styles, each with its own strengths and trade-offs. Understanding these differences will help you appreciate why REST became the dominant standard and when alternatives might be a better fit.

---

1. The Evolution of API Architectures

APIs have evolved significantly over the past 30 years. Each generation solved problems that the previous one could not handle well.

graph LR
    A["1990s<br/>RPC"] --> B["2000s<br/>SOAP"]
    B --> C["2000s<br/>REST"]
    C --> D["2015<br/>GraphQL"]
    C --> E["2016<br/>gRPC"]
    C --> F["WebSockets"]

    style A fill:#6b7280,color:#fff
    style B fill:#6b7280,color:#fff
    style C fill:#059669,color:#fff
    style D fill:#4f46e5,color:#fff
    style E fill:#4f46e5,color:#fff
    style F fill:#4f46e5,color:#fff

The Early Days: RPC (Remote Procedure Calls)

Before REST, the dominant paradigm was RPC — Remote Procedure Calls. The idea was simple: call a function on a remote server as if it were a local function. You would invoke something like getUserById(42) over the network.

The problem with RPC was tight coupling. The client had to know the exact function signatures on the server. Any change to the server required updating every client.

---

2. SOAP: The Enterprise Standard

SOAP (Simple Object Access Protocol) was developed in the late 1990s by Microsoft and became the enterprise API standard throughout the 2000s.

How SOAP Works

SOAP uses XML for everything — requests, responses, and even the service description. Every SOAP API has a WSDL (Web Services Description Language) file that describes all available operations.

A SOAP request to get a user:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <auth:Token xmlns:auth="http://example.com/auth">
      abc123token
    </auth:Token>
  </soap:Header>
  <soap:Body>
    <GetUser xmlns="http://example.com/users">
      <UserId>42</UserId>
    </GetUser>
  </soap:Body>
</soap:Envelope>

The equivalent REST request:

curl -H "Authorization: Bearer abc123token" \
  https://api.example.com/users/42

The difference in complexity is dramatic. SOAP requires an XML envelope, namespaces, headers within XML, and a body — all to do what REST does in one line.

SOAP Pros and Cons

Pros	Cons
Built-in error handling (SOAP Faults)	Extremely verbose (XML)
Formal contract (WSDL)	Complex to implement
WS-Security standard	Slow to parse
Transaction support	Not human-readable

Where SOAP Still Lives

SOAP is still used in legacy enterprise systems, banking, healthcare, and government integrations. If you work with payment processing or insurance APIs, you may encounter SOAP.

---

3. REST: The Web Standard

REST (Representational State Transfer) was defined by Roy Fielding in 2000 and is the subject of this entire course. REST leverages the existing infrastructure of the web — HTTP, URLs, and standard methods — instead of inventing new protocols.

Why REST Won

graph TD
    A[Why REST Dominates] --> B[Uses existing HTTP]
    A --> C[Human-readable URLs]
    A --> D[JSON format - lightweight]
    A --> E[Stateless - scalable]
    A --> F[Easy to learn]
    A --> G[Works everywhere]

    style A fill:#059669,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#0891b2,color:#fff
    style D fill:#0891b2,color:#fff
    style E fill:#0891b2,color:#fff
    style F fill:#0891b2,color:#fff
    style G fill:#0891b2,color:#fff

REST request:

curl https://api.example.com/users/42

REST response:

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.com"
}

Simple, clean, and readable. No boilerplate, no XML namespaces, no envelope wrappers.

---

4. GraphQL: The Query Language

GraphQL was developed by Facebook in 2012 and open-sourced in 2015. It solves specific problems that REST has with complex data fetching.

The Problem GraphQL Solves

With REST, you often face two issues:

Over-fetching: You only need a user's name, but the API returns everything:

GET /users/42
# Returns: id, name, email, address, phone, company, website, avatar...
# You only needed the name!

Under-fetching: You need data from multiple resources, requiring multiple requests:

GET /users/42           # First request: get the user
GET /users/42/posts     # Second request: get their posts
GET /users/42/followers # Third request: get their followers

How GraphQL Works

GraphQL uses a single endpoint and lets you specify exactly what data you want:

POST /graphql

{
  user(id: 42) {
    name
    posts {
      title
      comments {
        body
        author {
          name
        }
      }
    }
  }
}

One request, and you get exactly the data you asked for — no more, no less.

REST vs GraphQL Comparison

Feature	REST	GraphQL
Endpoints	Multiple (/users, /posts)	Single (/graphql)
Data fetching	Fixed response shape	Client chooses fields
Over-fetching	Common	Eliminated
Under-fetching	Requires multiple requests	Single request
Caching	Easy (HTTP caching)	More complex
Learning curve	Low	Medium
Error handling	HTTP status codes	Always 200, errors in response body
File uploads	Standard	Requires workaround
Real-time	Needs WebSockets	Subscriptions built-in

When to Use GraphQL

• Mobile apps needing minimal data transfer
• Complex UIs with nested relationships
• Backends serving many different clients
• When network round-trips are expensive

When to Stick with REST

• Simple CRUD applications
• Public APIs (REST is universally understood)
• When HTTP caching is important
• Server-to-server communication
• When simplicity matters most

---

5. gRPC: The Performance Champion

gRPC (Google Remote Procedure Call) was released by Google in 2016. It is designed for high-performance, low-latency communication between services.

How gRPC Differs

Instead of JSON over HTTP, gRPC uses:

• Protocol Buffers (Protobuf) for serialization — a binary format much smaller than JSON
• HTTP/2 for transport — enabling multiplexing and streaming
• Strict contracts defined in .proto files

A Protobuf definition:

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse);
  rpc ListUsers (Empty) returns (stream UserResponse);
}

message UserRequest {
  int32 id = 1;
}

message UserResponse {
  int32 id = 1;
  string name = 2;
  string email = 3;
}

gRPC vs REST

Feature	REST	gRPC
Format	JSON (text)	Protobuf (binary)
Speed	Fast	Very fast (up to 10x)
Human readable	Yes	No (binary)
Browser support	Full	Limited
Streaming	Limited	Built-in
Language support	Universal	Major languages
Use case	Web APIs	Microservices

When to Use gRPC

• Microservices communicating internally
• When latency is critical (real-time systems)
• When bandwidth is limited (IoT devices)
• Streaming data (live feeds, sensor data)

---

6. WebSockets: Real-Time Communication

WebSockets provide a persistent, bidirectional connection between client and server. Unlike HTTP (request-response), WebSockets allow the server to push data to the client without the client asking for it.

sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: HTTP - Request/Response
    Client->>Server: GET /data
    Server-->>Client: Response with data

    Note over Client,Server: WebSocket - Bidirectional
    Client->>Server: Open connection
    Server-->>Client: Connection accepted
    Server->>Client: New message!
    Server->>Client: Another update!
    Client->>Server: Send my message
    Server->>Client: Real-time update!

WebSocket Use Cases

Application	Why WebSockets
Chat applications	Messages push instantly
Live sports scores	Updates without refreshing
Stock tickers	Real-time price changes
Multiplayer games	Low-latency game state
Notifications	Push alerts immediately
Collaborative editing	Real-time document sync

WebSockets vs REST

• REST: Client always initiates. Good for CRUD operations.
• WebSockets: Either side can send. Good for real-time updates.

Most applications use both: REST for CRUD operations and WebSockets for real-time features.

---

7. Comparing All API Styles

graph TD
    A[Choose Your API Style] --> B{Need real-time?}
    B -->|Yes| C[WebSockets]
    B -->|No| D{Internal microservices?}
    D -->|Yes| E{Need max performance?}
    E -->|Yes| F[gRPC]
    E -->|No| G[REST]
    D -->|No| H{Complex nested data?}
    H -->|Yes| I[GraphQL]
    H -->|No| G

    style C fill:#d97706,color:#fff
    style F fill:#dc2626,color:#fff
    style G fill:#059669,color:#fff
    style I fill:#4f46e5,color:#fff

Criteria	REST	GraphQL	gRPC	WebSocket	SOAP
Ease of use	High	Medium	Medium	Medium	Low
Performance	Good	Good	Excellent	Excellent	Fair
Browser support	Full	Full	Limited	Full	Limited
Caching	Easy	Complex	Manual	N/A	Complex
Real-time	No	Subscriptions	Streaming	Yes	No
Best for	Web APIs	Complex UIs	Microservices	Live data	Legacy

---

8. Why This Course Focuses on REST

We focus on REST because:

1. It is the foundation. Understanding REST makes learning every other style easier.
2. It is the most common. 80%+ of public APIs use REST.
3. It is beginner-friendly. You can test REST with cURL, Postman, or a browser.
4. It is universal. Every language, framework, and platform supports REST natively.
5. It is the standard for API documentation. Most API docs describe REST endpoints.

Once you master REST, learning GraphQL or gRPC becomes much simpler because you already understand HTTP, methods, headers, status codes, and JSON.

---

Summary and Key Takeaways

1. SOAP is the legacy enterprise standard — verbose XML, complex but feature-rich.
2. REST is the web standard — simple, HTTP-based, JSON, and universally supported.
3. GraphQL solves over-fetching and under-fetching by letting clients choose their data.
4. gRPC is the performance champion for internal microservice communication.
5. WebSockets enable real-time, bidirectional communication.
6. REST is the foundation — learn it first, and everything else becomes easier.

---

Lesson Review Quiz