RESTful Web APIs (Leonard Richardson, Mike Amundsen, Sam Ruby)（Z-Library）

【One-Line Pitch】 A practical guide to designing REST APIs that actually earn the name—usable, evolvable, and built on the same hypermedia principles that made the Web succeed. Best for backend and API designers who already know HTTP basics and want to move beyond "almost-RESTful" CRUD endpoints. 【Book Arc】 - **Opening (~0%–10%)**: Frames the core problem—REST won the marketing war but most "RESTful" APIs are only REST-ish, and hypermedia remains genuinely hard. Sets up the book's mission: reuse existing standards instead of reinventing the 58th microblogging API. - **Early (~10%–30%)**: Establishes foundations—resources, representations, addressability, and the protocol semantics of HTTP methods (GET, POST-to-append, PUT, DELETE). Walks through a simple Collection+JSON microblog API to ground the theory. - **Middle (~30%–55%)**: Moves into hypermedia mechanics—the Link header, link relations, and how hypermedia ties representations into a coherent API. Uses the Maze+XML example to show how clients navigate and how server-side changes can stay hidden from clients. - **Late (~55%–85%)**: Tackles the "semantic challenge" with profile formats (XMDP, ALPS) and surveys standardized hypermedia data formats, plus resource description and Linked Data approaches (RDF, JSON-LD). - **Ending (~85%–100%)**: Extends REST beyond HTTP with CoAP for embedded systems, and closes with reference appendices—a status code codex, header codex, and an API designer's guide to the Fielding dissertation. 【Key Takeaways】 - **REST is a marketing buzzword as much as a technical term** (Opening): the book's central diagnosis is that most public APIs pay lip service to REST while skipping the architectural benefits—hypermedia, evolvability, self-descriptive messages. - **Addressability is the foundation** (Early): every resource needs its own URL; without a URL you can't get a representation, and without representations there's no representational state transfer. - **HTTP methods carry precise semantics** (Early): POST-to-append creates resources (201 + Location), PUT modifies state, and POST is neither safe nor idempotent—understanding these distinctions is what separates real REST from RPC-over-HTTP. - **Hypermedia is what makes an API coherent** (Middle): link relations and controls (including the Link header) let clients discover and navigate without hardcoding URLs, which is the key to long-term evolvability. - **The semantic gap is the hard problem** (Middle): machines can't infer meaning from titles like "The Entrance Hallway"—profile formats like XMDP and ALPS exist to bridge that gap. - **Standards reuse beats reinvention** (Early): open standards carry design review and patent protection; the book repeatedly argues for adopting existing formats rather than fiat standards. - **REST is not tied to HTTP** (Ending): CoAP demonstrates that REST principles apply in constrained embedded environments, showing the architecture's generality. - **Fielding's dissertation is the source of truth** (Ending): the appendix maps the original constraints to practical API design decisions. 【Reading Tips】 - **Deep-read the HTTP semantics chapters** (Early): the POST/PUT/DELETE distinctions and status codes are the most immediately applicable material for day-to-day API work. - **Skim the format survey, return to it as reference**: the catalog of ~two dozen hypermedia formats is breadth-first; bookmark it and revisit when choosing a format for a real project. - **Work through the Maze+XML example carefully** (Middle): it's the book's clearest demonstration of how hypermedia clients and servers evolve independently—the payoff is worth the effort. - **Treat the appendices as a working reference**: the Status Codex, Header Codex, and Fielding guide are designed for lookup, not linear reading. - **If you're new to hypermedia, expect the middle to be the hard part**: the semantic challenge and profile formats are conceptually dense; slow down there rather than rushing to the CoAP ending. 【Coverage Limits】 The excerpts cover the book's framing, HTTP fundamentals, hypermedia mechanics, and the CoAP ending, but the detailed content of the format survey, profile formats (XMDP/ALPS), and Linked Data chapters is only partially represented—specific format comparisons and JSON-LD examples are not fully covered here.