Learning API Styles (for Raymond Rhine) (Lukasz Dynowski, Marcin Dulak)（Z-Library）

# Learning API Styles — Reading Guide ## 【One-Line Pitch】 A practical, hands-on guide for developers and architects who want to understand the trade-offs between major API styles—REST, GraphQL, gRPC, webhooks, WebSocket, and message brokers—and learn how to choose and implement the right one for their use case. If you're building network-based APIs and want to move beyond "REST is the default," this book gives you the conceptual framework and working code examples to make informed decisions. ## 【Book Arc】 - **Opening (~0%–10%)**: Defines what network-based APIs are, distinguishes synchronous vs. asynchronous communication, and introduces functional vs. nonfunctional requirements as the lens for evaluating API styles. Sets up the book's scope: six API styles covered in dedicated chapters, with a deliberate focus on the role of network protocols—an often-overlooked aspect. - **Early (~10%–23%)**: Covers API design fundamentals that apply across all styles: versioning strategies (with deprecation and retirement dates), resource-oriented vs. intent-oriented API design (declarative vs. imperative), filtering approaches, request retry patterns (including thundering herd and retry storm problems), and security basics like sanitization, validation, and least privilege. - **Early (~23%–32%)**: Dives into the network layer—DNS, TCP, and TLS—with hands-on labs using Python Socket API and Docker containers. You'll implement a TCP ECHO service three ways (command-line tool, low-level Python, high-level socket API) and observe TLS handshakes in packet captures. This groundwork explains *why* protocols behave as they do. - **Middle (~32%–42%)**: Traces HTTP evolution from HTTP/0.9 through modern versions, including HTTP/3 over QUIC. You'll examine real packet captures, understand headers like ETag and Keep-Alive, and learn about head-of-line blocking and the deployment realities of HTTP/3 (middlebox compatibility, cloud platform support). - **Middle (~42%–48%+)**: Begins the API-style chapters with REST—URI anatomy, stateless interaction, resource organization (including when to avoid nesting endpoints), and versioning in practice. Includes working examples with Docker, curl, and JSON payloads. ## 【Key Takeaways】 - **Functional vs. nonfunctional requirements are the right lens for API selection** (Early): FRs describe what the system does; NFRs describe quality attributes ("ilities" like deployability, scalability). Classifying requirements this way helps prioritize design efforts and communicate risks before committing to an API style. - **Resource-oriented APIs are declarative; intent-oriented APIs are imperative** (Early): REST uses standard HTTP verbs to abstract implementation details (declarative), while gRPC names actions explicitly (imperative). GraphQL mixes both—declarative queries with imperative mutations. This distinction clarifies why different styles feel different to use. - **API versioning requires explicit deprecation and retirement dates** (Early): Notify users through multiple channels—CLI warnings (Kubernetes), documentation banners (Google PaLM API), or HTTP headers like `Deprecation` and `Sunset`. A versioning strategy without a retirement plan leaves users stranded. - **Retry logic needs protection against retry storms** (Early): Blind retries can prolong outages (thundering herd problem). Use maximum retry cutoffs with expiration timers, or a circuit-breaker pattern that tracks success/failure ratios. Knowing *when not to retry* is as important as knowing when to. - **Never trust input data—sanitize and validate everything** (Early): Sanitization removes unwanted input (unexpected characters, whitespace); validation enforces constraints (ranges, formats). Without both, injection attacks and data breaches become possible. Apply least privilege to API clients. - **Network protocols shape API behavior more than most API books acknowledge** (Early–Middle): DNS maps names to IPs, TCP provides reliable in-order delivery (but with head-of-line blocking), TLS adds handshake overhead. Understanding these layers explains why HTTP/3 over QUIC exists and why it isn't universally deployed yet. - **HTTP/3's real advantage may be as a QUIC deployment vehicle** (Middle): While HTTP/3 offers header compression and reduced connection latency, it faces adoption barriers—middleboxes that block UDP, cloud platforms requiring proxies, and TLS 1.3 compatibility issues. Its broader impact may be enabling new protocols (SMB over QUIC, WebTransport). ## 【Reading Tips】 - **Skim the early requirement-classification sections** (~10%) if you're already familiar with FR/NFR thinking; the real value starts with the design patterns (versioning, filtering, retries) around ~13–23%. - **Deep-read the network chapters** (~23–32%) even if you're not a network engineer—the TCP ECHO lab and TLS handshake walkthroughs make abstract protocol concepts concrete. The Docker-based labs are worth running hands-on. - **The HTTP evolution chapter** (~32–42%) is best read as context, not reference—you don't need to memorize HTTP/0.9 details, but understanding *why* headers and status codes exist helps when designing REST APIs later. - **Watch for the recurring trade-off framework**: each API style chapter (REST, GraphQL, gRPC, webhooks, WebSocket, RabbitMQ) evaluates the style against network, application, and architecture perspectives. Use this framework to compare styles for your own projects. - **The REST chapter** (~42–48%+) includes practical examples with Docker, curl, and JSON—follow along if you want implementation experience, but the design guidance (resource organization, versioning) is valuable even without running the code. ## 【Coverage Limits】 This guide covers the book's opening through the early REST chapter (~48%). The excerpts do not cover the GraphQL, gRPC, webhooks, WebSocket, or RabbitMQ chapters in detail, nor the book's exercises and setup instructions beyond what appears in the sampled sections. ##