Learning API Styles • Lukasz Dynowski & Sam Newman • GOTO 2026
This GOTO Book Club episode features an in-depth conversation between Sam Newman and Lukasz Dynowski, co-author of "Learning API Styles," exploring the foundational network layer of APIs, various API styles, critical trade-off decisions, and future trends like WebTransport and gRPC. The discussion emphasizes treating APIs as products, understanding consumer context, and the eight key characteristics of a well-designed API, complemented by a cautionary tale on database access.
Lukasz Dynowski, co-author of “Learning API Styles,” and Sam Newman, author of “Building Microservices,” engage in a deep dive into the foundational and practical aspects of APIs. Their discussion, framed around Dynowski’s book, highlights the complexities often overlooked by developers focused solely on high-level protocols.
Starting from the Network Layer
Dynowski explains the deliberate choice to begin the book at the network layer, rather than immediately discussing REST or GraphQL. He argues that a true understanding of APIs requires delving into the underlying substrate, such as:
- Transmission modes: Simplex, full duplex, and half duplex.
- Synchronous vs. asynchronous processing.
- Protocol levels: Understanding how the 7th layer of the OSI model abstracts away lower-level complexities until bottlenecks arise. This involves knowing the magic of networking, which can be crucial when diagnosing issues like TCP/IP pool exhaustion or analyzing Wireshark packet captures. The goal is a 360-degree view from networking to implementation and trade-offs, moving beyond high-level governance discussions.
Sam Newman noted the value of revisiting these “first principles” and the surprising commonality across different abstraction layers.
Audience and Reproducibility
The book targets three main audiences:
- Software architects: To understand the trade-offs of individual API styles.
- Developers: To learn how to implement each style with practical examples.
- Both: To demystify the workings of networking.
A key focus for the authors was reproducibility. The book includes numerous code examples, supported by a YouTube playlist demonstrating setup and execution, and a GitHub repository with GIFs for every exercise. This ensures readers can replicate and understand the concepts.
Public vs. Private APIs: The “API as a Product” Mentality
Dynowski advocates for approaching API development with a “public perspective,” treating APIs as products that will eventually be exposed externally. This mindset, he notes, aligns with Jeff Bezos’s “API Mandate” at Amazon, which emphasized APIs as a means to potentially monetize business capabilities. While internal (private) APIs allow for more assumptions due to closer communication with consumers, adopting a public API mindset better prepares for wider, external consumption. He stresses that API development is a “human-centric” activity, requiring collaboration across various roles like product owners, scrum masters, and testers.
Making Informed API Trade-off Decisions
Effective API design hinges on aligning with non-functional requirements (NFRs). Key considerations include:
- Security: Encompassing authentication (verifying client identity), authorization (ensuring actions stay within assigned permissions), and encryption (for data in transit and at rest). An example given was RabbitMQ’s default unencrypted persistence, necessitating explicit encryption for self-hosted solutions.
- Audience: The choice of API style should be tailored to the consumer (e.g., IoT devices, mobile apps, web browsers, or other programs).
- Data Transfer: The decision between binary and textual protocols. While REST’s text-based payloads (ASCII/UTF) aid debugging by allowing developers to easily inspect messages, binary protocols can offer performance benefits but complicate introspection. Sam Newman points out that “faster” is only relevant if efficiency targets are met; an easier-to-use textual protocol might be perfectly adequate.
- Flexibility and Context: Systems are not limited to a single API stack. Different styles can be used for “north-to-south” (client-to-backend) and “east-to-west” (microservice-to-microservice) communication. For instance, REST might serve client-facing interactions, while webhooks or message brokers handle internal communications. Proximity of clients also influences choices (e.g., gRPC for internal, HTTP for external due to firewall compatibility).
Architects, Dynowski concludes, need not have all the answers but should understand the directions dictated by quality attributes and be prepared to accept the consequences of their decisions.
The Future Landscape of APIs
Dynowski discusses emerging technologies that could shape future API development:
- WebTransport: Positioned as a successor to WebSockets, aiming to address its shortcomings, and a technology Dynowski will closely monitor once stable.
- gRPC: A powerful protocol built on UDP/QUIC, offering diverse communication patterns: unicast, client streaming, server streaming, and bidirectional streaming. gRPC’s ability to facilitate custom application-level protocols is intriguing, though real-world adoption beyond specific use cases remains niche. Sam notes its growing appeal in microservices environments for its IDL-driven client stub generation, simplifying integration compared to manual REST bindings. The integration of RPC into the gRPC framework within Next.js indicates its increasing relevance in the JavaScript ecosystem.
Defining a “Good API”
Drawing on Joshua Bloch’s observations, Lukasz outlines characteristics of a good API:
- Audience-aware: Designed with its consumers in mind.
- Maintainable: Allows for new functionality without breaking existing clients.
- Efficient: Resource-conscious (TCP connections, latency, database interactions).
- Intuitive: Enables users to form a correct mental model and assumptions.
- Hard to misuse: Provides clear feedback (e.g., status codes) when used incorrectly.
- Secured: Implements authentication, authorization, and encryption.
- Testable: Facilitates end-to-end and fuzzy testing.
- Well-documented: Features minimal divergence between specifications (like OpenAPI) and actual behavior.
Sam Newman recounts a “war story” from a credit derivatives system where multiple clients shared the same database credentials. The only way to identify who was accessing the database was to disable the account and await angry phone calls, underscoring the critical importance of robust security practices and distinct access controls from the outset.