API Architectural Styles

APIs can be designed and implemented in different architectural styles. Each style has its own principles, strengths, and trade-offs. Choosing the right styles depends on the system's requirements, such as performance, flexibility, scalability, and developer experience.

1️⃣ REST (Representational State Transfer)

This is most widely used API style. It is based on resources (users, order, products).

Client --------HTTP Request--------> Server
       <-------HTTP Response---------

It uses HTTP verbs for operations:

• GET: Read
• POST: Create
• PUT/PATCH: Update
• DELETE: Remove

Example:

GET /api/v1/users/123

Response:

{
  "id": 123,
  "name": "Manish",
  "email": "manish@example.com"
}

Key Principles:

• Stateless requests (server does not store client context).
• Uniform interface (consistent endpoint design).
• Cacheable responses (via HTTP caching headers).

Pros:

• Simple, widely adopted, easy to understand.
• Uses standard web infrastructure (HTTP).
• Good for CRUD operations.

Cons:

• Over-fetching or under-fetching of data.
• Limited in real-time scenarios.

2️⃣ GraphQL

A query language and runtime for APIs (developed by Facebook). Clients request exactly the data they need. It uses a single endpoint (/graphql).

Client -------- GraphQL Query --------> Server
       <------ JSON Response (exact fields requested) ------

Example Query:

Query:

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

Response:

{ 
"user": 
       {
         "name": "Manish",
         "email": "manish@example.com"
       }
}

Pros:

• No over-fetching or under-fetching.
• Strongly typed schema improves developer experience.
• Great for mobile and frontend-heavy applications.

Cons:

• More complex to implement and secure.
• Can lead to performance issues with deeply nested queries.
• Requires schema management and query analysis.

3️⃣ gRPC (Google Remote Procedure Call)

High-performance, open-source RPC framework like Google. It uses Protocol Buffers (protobuf) for serialization. Designed for service-service communication in microservices.

Client -------- Protobuf Request --------> Server
       <------- Protobuf Response --------

Example:

Request:

UserRequest { id: 123 }

Response:

UserResponse { id: 123, name: "Manish", email: "manish@example.com" }

Pros:

• Extremely fast and efficient (binary format).
• Built-in streaming support (client, server, bidirectional).
• Strongly typed contacts.
• Ideal for internal microservice communication.

Cons:

• Not as human-readable as REST/JSON.
• Requires client code generation.
• Limited browser support (uses gRPC-Web instead).

4️⃣ WebSockets

Enable persistent, bidirectional communication over a single TCP connection. Used for real-time applications like chat, stock tickers, multiplayer games.

Client <==== Persistent Connection (WS) ====> Server

Example:

• Client subscribed to ws://api.example.com/chat.
• Server pushes new messages instantly without polling.

Client sends: "Hello!"
Server pushes: "Hi Manish!"

Pros:

• True real-time communication.
• Efficient for event-driven applications.
• Reduces latency by avoiding repeated requests.

Cons:

• More complex than stateless APIs.
• Harder to scale (requires sticky sessions or message brokers).
• Not ideal for simple CRUD systems.

5️⃣ Event-driven APIs (Webhooks & Pub/Sub)

Instead of client pulling data, the server pushes events. It can be implemented with webhooks or pub/sub systems.

Event Source ----> Event Broker (Pub/Sub) ----> Consumers

Examples:

• Stripe sends a webhook when a payment succeeds.
• GitHub sends events for pushes or pull requests.

Pros:

• Efficient (no polling).
• Decouples producers and consumers.
• Great for asynchronous workflows.

Cons:

• Requires reliable delivery mechanisms (retry, queueing).
• Harder debugging and monitoring.
• More complex to design than request/response APIs.