System Design Chapter 9

API Design, Protocols & Architecture

Network Stack, HTTP vs HTTPS, Core API Styles, Lifecycle Management & Key Principles

★ Essential for client-server communication, microservices & scalable system design!

1 API Fundamentals & Client-Server Contract

API (Application Programming Interface) defines how software components interact and communicate with each other.

✏️ The API Client-Server Contract Architecture

💻 Client

Browser / Mobile

➔ Request / Response ➔

📜 API Contract Defines:

What requests can be made
How to make requests
What responses to expect

➔

🖥️ Server

Backend Engine

🧱 1. Abstraction Mechanism

Hides internal implementation details (DB schema, business logic) while safely exposing necessary functionality to external consumers.

🌐 2. Service Boundaries

Establishes clear, isolated boundaries between distinct system components, enabling decoupled client-server apps and distributed microservices.

2 API Protocols in the Network Stack

⚠️ Protocol Selection Rule:

“Choosing wrong protocols can lead to performance bottlenecks and limitations in functionality.”

Application-level communication protocols operate at the topmost layer of the standardized network stack:

📡 Application Protocols in the 5-Layer Network Stack

🚀Application Layer (API Focus)

HTTP / HTTPSWebSocketsgRPCMQTTAMQP

🚚Transport Layer

TCPUDP

🗺️Network Layer

IP (IPv4 / IPv6)

🔗Data Link Layer

EthernetWi-FiBluetooth

🔌Physical Layer

Cables, Radio Frequencies & Fiber

3 HTTP (Hypertext Transfer Protocol) Deep Dive

HTTP is the foundational stateless request-response protocol of the World Wide Web and modern web APIs.

📤HTTP Request Anatomy

GET /api/products/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer token
Accept: application/json

Client sends method, path, headers (auth, host) and optional payload.

📥HTTP Response Anatomy

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600

{ “id”: 123, “price”: 19.99 }

Server responds with status code, metadata headers, and formatted data payload.

⚡ 5 Core HTTP Methods (CRUD Operations)

HTTP Method	Action / Intent	Description & Idempotence
GET	Retrieve Data	Fetches resource data without modifying server state (Safe & Idempotent).
POST	Create Data	Creates a new subordinate resource on the server (Non-idempotent).
PUT	Update Data (Full)	Replaces the target resource entirely with new payload (Idempotent).
DELETE	Remove Data	Deletes the specified resource permanently (Idempotent).
PATCH	Partial Update	Modifies specific fields of an existing resource without full overwrite.

🔢 HTTP Status Code Categories

2xx (Success): Request was received, understood, and accepted (e.g. 200 OK, 201 Created).
3xx (Redirection): Further action needed to complete request (e.g. 301 Moved, 304 Not Modified).
4xx (Client Error): Invalid request or unauthorized client (e.g. 400 Bad Request, 401 Unauthorized, 404 Not Found).
5xx (Server Error): Server failed to fulfill a valid request (e.g. 500 Internal Error, 502 Bad Gateway, 503 Service Unavailable).

📋 5 Common HTTP Headers

Content-Type: Tells client/server MIME type of data (e.g. application/json).
Authorization: Carries credentials/tokens for authentication (e.g. Bearer <token>).
Accept: Specifies media types acceptable for the response.
Cache-Control: Directives for caching mechanisms in browsers/CDNs (e.g. max-age=3600).
User-Agent: Identifies the requesting browser, OS, and client software.

4 HTTPS (HTTP + TLS/SSL Encryption)

🔒 What is HTTPS?

HTTPS = HTTP + TLS/SSL Encryption
Protects data in transit from eavesdropping, interception, and tampering across public networks.

🛡️ Key Benefits of HTTPS

Data Encryption: Encrypts transmitted packets so eavesdroppers cannot read raw sensitive data.
Data Integrity: Detects and prevents any data alteration, packet injection, or corruption during transit.
Authentication: Verifies server identity via trusted SSL/TLS certificates, preventing DNS spoofing.
SEO Benefits: Search engines (e.g. Google) penalize plain HTTP and rank HTTPS websites higher.

⚠️ Critical Risks Without HTTPS

Man-in-the-Middle (MITM) Attacks: Adversaries on public Wi-Fi intercept and monitor plain data streams.
Data Tampering: Bad actors inject ads, malicious scripts, or alter transaction payloads in transit.
Information Theft: Cleartext passwords, session cookies, credit card numbers, and PII get stolen.
Loss of User Trust: Modern browsers display red “Not Secure” warnings, driving visitors away.

5 Core API Architectural Styles: REST, GraphQL, & gRPC

🌐 1. REST (Representational State Transfer)

The universal industry-standard API architectural style for web, cloud, and mobile clients.

📦 Resource-Based:

Structured around intuitive resource endpoints (e.g. /api/v1/users, /api/v1/orders) using standard HTTP methods.

🔒 Stateless:

Every request contains complete authorization and parameters; server retains no client session state between requests.

🕸️ 2. GraphQL (Minimal Round Trips & Precise Fetching)

A client-driven query language for APIs that eliminates over-fetching and under-fetching.

🎯 Single Endpoint:

All client queries and mutations route through a single unified endpoint (e.g. /graphql).

⚡ 3 Core Operations:

Query ➔ Read and retrieve exact required fields
Mutation ➔ Create, update, or delete server data
Subscription ➔ Real-time WebSocket event streaming

💡 Recommended Choice for: Complex frontend UIs, mobile apps with bandwidth constraints, and aggregating multi-service dashboards into a single request.

🚀 3. gRPC (High Performance Binary RPC)

A high-throughput, low-latency Remote Procedure Call framework created by Google for microservices.

⚡ Protocol Buffers (Protobuf):

Uses ultra-compact binary serialization instead of heavy JSON text, cutting bandwidth and parse overhead.

📄 Service Definition (.proto):

Strict contract-first schemas defined in .proto files with auto-generated client/server SDKs in multiple languages.

📡 4 Communication Streaming Modes:

1️⃣ Unary
Single Req ➔ Single Resp

2️⃣ Server Streaming
Single Req ➔ Stream Resp

3️⃣ Client Streaming
Stream Req ➔ Single Resp

4️⃣ Bidirectional
Two-way continuous stream

💡 Best Suited For: Internal backend-to-backend microservices, high-frequency trading, and IoT telemetry pipelines.

6 API Design Process, Approaches & Lifecycle Management

📋 4 Requirements Discovery Steps

1. Identify Core Use Cases

Map out end-user stories, workflows, and developer interaction patterns.

2. Define Scope & Boundaries

Establish bounded domains, clear responsibilities, and external dependencies.

3. Determine Performance Needs

Specify latency budgets, throughput limits (QPS), and payload size targets.

4. Consider Security Constraints

Define authentication protocols, RBAC authorization, and data privacy regulations.

📐 3 Core API Design Approaches

🔝 Top-Down Approach

Start with high-level user requirements and client workflows, then design API contracts and database models downward.

🔄 Bottom-Up Approach

Begin with existing databases, domain models, and internal system capabilities, then expose API endpoints upward.

📜 Contract-First Approach

(Industry Best Practice) Formally define and approve the API contract (OpenAPI/Swagger, Proto) before writing any implementation code.

🔄 API Lifecycle Management Flow

Stage 1
✏️ Design

➔

Stage 2
💻 Development

➔

Stage 3
🚀 Deployment & Monitoring

➔

Stage 4
🔧 Maintenance

➔

Stage 5
🛑 Deprecation & Retirement

7 Key API Design Principles

📏 1. Consistency

Consistent Naming: Plural nouns for collections (/users, /orders), predictable casing.
Consistent Patterns: Uniform error schemas, status codes, and pagination metadata structures.

✨ 2. Simplicity

Focus on Core Use Cases: Solve the 80% developer needs first without over-engineering edge cases.
Intuitive Design: Easy-to-guess URL structures and predictable parameter responses.

🔒 3. Security

Authentication & Authorization: Verify identity (OAuth2/JWT) and enforce strict role-based access controls.
Input Validation & Rate Limiting: Sanitize payload fields to stop injection and prevent runaway abuse.

⚡ 4. Performance

Caching Strategies: Use Cache-Control headers, ETags, and Redis edge layers.
Pagination & Payloads: Limit default result sets, compress data (Gzip/Brotli), and reduce network round-trips.

“

The best API is one developers can use without reading documentation.

— Core System Design Philosophy