REST (Representational State Transfer)

REST is an architectural style based on HTTP that models resources as URLs and uses standard HTTP methods for state transitions. It’s the de facto standard for public APIs due to its simplicity, wide tooling support, and HTTP ecosystem integration.

Core Principles

• Resource-Oriented: Resources are identified by URIs and manipulated through standard HTTP methods. Resources are decoupled from their representations (JSON, XML, etc.).
• Stateless: Each request contains all necessary context. No server-side session state required, enabling horizontal scaling and simplified caching strategies.
• Uniform Interface: Standard HTTP methods (GET, POST, PUT, PATCH, DELETE) with well-defined semantics. Leverages HTTP status codes and headers for metadata.
• Cacheable: Responses must define cacheability. Enables CDN integration, reduces server load, and improves client performance.
• Layered System: Supports intermediary components (proxies, gateways, load balancers) without affecting client-server communication.

Architectural Trade-offs

GraphQL

GraphQL is a query language and runtime for APIs that enables clients to request exactly the data they need. Developed by Facebook to address mobile performance issues, it solves the over-fetching and under-fetching problems inherent in REST architectures.

Core Concepts

• Type System: Strongly-typed schema defines the API contract. Types, fields, and relationships are explicitly defined, enabling validation and tooling.
• Single Endpoint: All operations (queries, mutations, subscriptions) go through one endpoint, simplifying client configuration and reducing network complexity.
• Field Selection: Clients specify exact fields needed, eliminating over-fetching. Reduces payload size and improves mobile performance.
• Resolver Pattern: Each field has a resolver function that defines how data is fetched. Enables flexible data aggregation from multiple sources.
• Introspection: Schema is self-documenting and queryable, enabling powerful developer tooling and client code generation.

Architectural Trade-offs

Performance Considerations

gRPC (Google Remote Procedure Call)

gRPC is a high-performance RPC framework using Protocol Buffers for serialization and HTTP/2 for transport. It provides type-safe, language-agnostic service definitions with support for streaming and code generation.

Core Architecture

• Protocol Buffers: Binary serialization format providing 3-10x smaller payloads than JSON. Schema evolution through backward-compatible field additions. Enables efficient serialization/deserialization.
• HTTP/2 Transport: Multiplexing, header compression, server push capabilities. Reduces latency compared to HTTP/1.1, especially for multiple concurrent requests.
• Code Generation: Service definitions (.proto files) generate client/server code in multiple languages, ensuring type safety and reducing boilerplate.
• Streaming Support: Four communication patterns: Unary (request-response), Server Streaming, Client Streaming, Bidirectional Streaming. Enables efficient real-time data transfer.
• Interceptors: Middleware pattern for cross-cutting concerns (logging, authentication, rate limiting, tracing).

Architectural Trade-offs

Streaming Patterns

HTTP (HyperText Transfer Protocol)

HTTP is the foundation of data communication on the World Wide Web. It defines how messages are formatted and transmitted, and how web servers and browsers respond to various commands.

HTTP Methods

HTTP Status Codes

Common HTTP Headers

• Content-Type: Specifies the media type of the resource (e.g., application/json, text/html)
• Authorization: Contains credentials for authentication (e.g., Bearer token)
• Accept: Indicates which content types the client can process
• Cache-Control: Directives for caching mechanisms
• ETag: Entity tag for cache validation
• If-None-Match: Conditional request using ETag

HTTPS (HTTP + TLS/SSL Encryption)

HTTP Connection Pooling

HTTP connection pooling allows multiple requests to reuse the same TCP connection, reducing latency and improving performance.

WebSockets

WebSocket is a communication protocol that provides full-duplex communication channels over a single TCP connection. Unlike HTTP, which follows a request-response pattern, WebSocket allows both client and server to send messages at any time.

• Real-time Data: Enables bidirectional, real-time communication without polling
• Reduced Bandwidth: More efficient than HTTP polling – no repeated headers
• Bidirectional Communication: Both client and server can initiate messages
• Low Latency: Persistent connection eliminates handshake overhead
• Use Cases: Chat applications, live notifications, real-time gaming, collaborative editing

AMQP (Advanced Message Queuing Protocol)

AMQP is an open standard protocol for message-oriented middleware. It enables reliable, asynchronous messaging between applications and services.

Exchange Types

Benefits of AMQP

• Reliability: Message persistence and delivery guarantees
• Decoupling: Producers and consumers don’t need to know about each other
• Scalability: Can handle high message volumes
• Flexibility: Supports various messaging patterns

gRPC

Protocol Buffers: Schema-first interface definition language that compiles into strongly typed message classes. Messages use compact binary encoding, which keeps payloads small and enforces contracts between producers and consumers.

Client ↔ Server flow: The client uses generated stubs to invoke RPC methods as native function calls. Calls travel over HTTP/2, which provides multiplexed streams, header compression, and flow control. On the server side, generated service skeletons deserialize the request, execute business logic, and stream responses back.

Common Use Cases

• Microservices communication
• Polyglot systems (different languages)
• Real-time services

TCP (Transmission Control Protocol)

• Connection-oriented: Establishes connection before data transfer
• Reliable: Guarantees delivery and order of packets
• Flow control: Prevents overwhelming the receiver
• Error checking: Detects and retransmits lost packets
• Use cases: HTTP, HTTPS, WebSockets, gRPC, AMQP

UDP (User Datagram Protocol)

• Connectionless: No connection establishment needed
• Fast: Lower overhead than TCP
• Unreliable: No guarantee of delivery or order
• No flow control: Can overwhelm receiver
• Use cases: DNS, real-time gaming, video streaming, IoT sensors

Implementation Strategies

Idempotency Keys: Client sends unique key (UUID) in Idempotency-Key header. Server stores key with response, returns cached response for duplicate keys.

Natural Idempotency: Use resource identifiers or timestamps. Example: PUT /api/v1/products/123 is naturally idempotent.

Trade-offs: Idempotency keys require storage (Redis) and add complexity, but enable safe retries and prevent duplicate operations.

Webhook Implementation

Flow: Client registers webhook URL → API stores URL → Event occurs → API POSTs event to URL → Client acknowledges receipt

Best Practices: Sign webhooks (HMAC), implement retries with exponential backoff, use idempotency keys, provide webhook management API, log all delivery attempts, support webhook verification.

Problem Details Format

Benefits: Standardized format, machine-readable, includes context (type, instance), enables better error handling in clients.

Token Bucket Algorithm

Maintains a bucket of tokens. Each request consumes a token. Tokens refill at a fixed rate. Allows bursts up to bucket capacity.

Use Cases: APIs that need to allow bursts, variable request rates

Implementation: Redis with atomic operations, or dedicated rate limiting service

Sliding Window Log

Maintains a log of request timestamps. Counts requests within time window. More accurate than fixed window but requires more storage.

Use Cases: When precise rate limiting is required, distributed systems

Implementation: Redis sorted sets (ZSET) with timestamps as scores

Fixed Window

Divides time into fixed windows (e.g., 1 minute). Counts requests per window. Simple but allows bursts at window boundaries.

Use Cases: Simple rate limiting, when burst tolerance is acceptable

Implementation: Redis counters with TTL

Consumer-Driven Contracts

Clients define expected API contract. Provider tests against consumer expectations. Ensures backward compatibility.

Tools: Pact (consumer-driven contracts), Spring Cloud Contract, OpenAPI contract testing

Benefits: Prevents breaking changes, enables independent deployment, improves confidence in API changes

TLS and Authentication

• Enable mTLS between services; rotate certificates via automated CA (SPIRE, cert-manager).
• Propagate identity via x509 SAN or JWT metadata; enforce authorization with interceptors.
• Use interceptors for rate limiting, auditing, and policy enforcement (OPA, AWS Cedar).

Observability

• Inject tracing metadata (B3/W3C) through gRPC metadata; export traces via OpenTelemetry.
• Log request/response metadata (method, status, latency) with structured logging.
• Expose health checks via `grpc.health.v1.Health/Check` for orchestration systems.

Basic Authentication

HTTP Basic Authentication transmits credentials (username:password) as Base64-encoded strings in the Authorization header. While simple to implement, it has significant security limitations and should only be used over HTTPS.

Implementation Details

Credentials are sent in the format: Authorization: Basic base64(username:password)

Security Considerations

Basic Auth Mechanism

• Username + Password
• Base64 encoding of username:password
• Sent in Authorization header: Authorization: Basic base64(username:password)

Practical Example

Bearer Tokens

This is the standard approach in API design today. It’s fast and stateless, making it ideal for modern applications.

OAuth2 + JWT

OAuth2 is an authorization framework that allows applications to obtain limited access to user accounts. JWT (JSON Web Token) is a compact, URL-safe token format used to securely transmit information between parties.

OAuth2 Authorization Code Flow

• Used in “Login with Google”, “Login with GitHub”, “Login with Facebook”
• JWT tokens are stateless – you don’t need to store sessions
• OAuth2 provides secure authorization framework
• Delegated authorization – user grants permission without sharing password

JWT Structure

Format: header.payload.signature

Benefits: Stateless, self-contained, compact, verifiable

JWT Implementation Example (Node.js)

Login Flow Example

Access and Refresh Tokens

Token Refresh Implementation

Single Sign-On (SSO) and Identity Protocols

SSO enables users to authenticate once and access multiple applications without re-entering credentials. This reduces password fatigue, improves security through centralized identity management, and simplifies user experience.

SAML 2.0 (Security Assertion Markup Language)

XML-based protocol for enterprise SSO. Common in B2B scenarios and enterprise identity providers.

• Use Cases: Enterprise SSO, B2B integrations, legacy systems
• Architecture: Identity Provider (IdP) issues SAML assertions, Service Provider (SP) validates them
• Flow: SP redirects to IdP → User authenticates → IdP returns SAML assertion → SP validates and grants access
• Trade-offs: XML overhead, complex setup, but mature and widely supported in enterprise

OAuth2 / OpenID Connect (OIDC)

OAuth2 is an authorization framework; OIDC extends it for authentication. JSON-based, modern standard for consumer and enterprise applications.

• OAuth2: Authorization delegation – allows apps to access resources on behalf of users
• OIDC: Authentication layer on top of OAuth2 – provides identity information (ID tokens)
• Use Cases: “Login with Google/Facebook”, API authorization, mobile app authentication
• Flows: Authorization Code (web), Implicit (deprecated), Client Credentials (service-to-service), Device Code (IoT)
• Advantages: JSON-based, RESTful, mobile-friendly, widely adopted

Protocol Selection

RBAC (Role-Based Access Control)

Permissions are assigned to roles, users are assigned roles. Simplifies management through role hierarchies and inheritance.

Implementation: User → Roles → Permissions. Roles can be hierarchical (admin inherits editor permissions).

Use Cases: Most common model. Good for organizations with clear role structures (admin, editor, viewer).

Trade-offs: Simple to implement and understand, but can become complex with many roles. Role explosion problem in large systems.

ABAC (Attribute-Based Access Control)

Access decisions based on attributes of subject (user), resource, action, and environment (time, location, IP).

Implementation: Policy engine evaluates rules: “Allow if user.department == resource.department AND time.between(9am, 5pm)”.

Use Cases: Complex authorization requirements, dynamic permissions, fine-grained access control, compliance requirements.

Trade-offs: Highly flexible and expressive, but complex to implement and maintain. Requires policy engine (XACML, Rego, custom).

ACL (Access Control List)

Each resource maintains a list of identities and their permissions. Direct user-resource permission mapping.

Implementation: Resource stores: [{userId: 123, permissions: [‘read’, ‘write’]}, …]. Check if user ID in list with required permission.

Use Cases: File systems, document sharing, fine-grained per-resource permissions.

Trade-offs: Very flexible per-resource, but doesn’t scale (large ACLs), difficult to manage at scale, no role abstraction.

Policy-Based Authorization

Centralized policy engine evaluates authorization rules. Policies defined in declarative language (Rego, Cedar, XACML).

Implementation: Authorization service (e.g., Open Policy Agent, AWS IAM, Auth0 Fine-Grained Authorization) evaluates policies against request context.

Use Cases: Multi-tenant SaaS, complex authorization logic, when authorization logic needs to be externalized from application code.

Trade-offs: Centralized management, testable policies, but adds latency (policy evaluation), requires policy language expertise.

1. Rate Limiting

Rate limiting controls the number of requests a client can make to your API within a specific time period. This prevents abuse and ensures fair usage.

• Per endpoint: Different limits for different endpoints (e.g., login: 5/min, search: 100/min)
• Per IP/User: Limit requests from specific sources to prevent abuse
• Overall: Global rate limits to mitigate DDoS attacks
• Strategies: Token bucket, sliding window, fixed window

Rate Limiting Implementation (Node.js with express-rate-limit)

2. CORS (Cross-Origin Resource Sharing)

CORS controls which domains can access your API from browsers. It’s a security mechanism that prevents unauthorized cross-origin requests.

• Same-Origin Policy: Browsers block requests from different origins by default
• CORS Headers: Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers
• Preflight Requests: OPTIONS requests to check if actual request is allowed
• Best Practice: Whitelist specific origins, not “*”

CORS Implementation (Node.js with Express)

3. SQL Injection Prevention

SQL injection occurs when attackers insert malicious SQL code into input fields, potentially gaining unauthorized access to your database.

• Parameterized Queries: Use prepared statements with placeholders
• Input Validation: Validate and sanitize all user inputs
• Least Privilege: Database users should have minimal required permissions
• ORM Usage: Object-Relational Mapping tools provide built-in protection

4. Firewalls

Firewalls provide network-level protection by filtering traffic based on security rules. They can block malicious requests before they reach your API.

• Web Application Firewall (WAF): Protects against common web exploits
• Network Firewall: Controls traffic at network boundaries
• IP Whitelisting: Allow only specific IP addresses
• DDoS Protection: Mitigate distributed denial-of-service attacks

5. VPN (Virtual Private Network)

VPNs encrypt network traffic and provide secure remote access. They’re useful for protecting API communication in corporate environments.

• Encryption: All traffic is encrypted in transit
• Secure Tunneling: Creates secure connection over public networks
• Access Control: Restricts API access to authorized users
• Use Cases: Internal APIs, B2B integrations, remote access

6. CSRF (Cross-Site Request Forgery)

CSRF attacks trick authenticated users into performing unwanted actions on a web application where they’re authenticated.

• CSRF Tokens: Unique tokens for each session/request
• SameSite Cookies: Prevents cookies from being sent in cross-site requests
• Origin Validation: Check Origin and Referer headers
• Double Submit Cookie: Cookie and form field must match

7. XSS (Cross-Site Scripting)

XSS attacks inject malicious scripts into web pages viewed by other users. These scripts can steal data, hijack sessions, or deface websites.

• Input Sanitization: Remove or encode dangerous characters
• Content Security Policy (CSP): Restrict which scripts can run
• Output Encoding: Encode user input when displaying
• HttpOnly Cookies: Prevent JavaScript access to cookies