liveBook · Manning

Chapter 6: Reliable API Design: Public Contracts and Synchronous Communication

What you will learn in chapter 6 of Grokking Software Architecture

This chapter introduction previews API contracts, REST and GraphQL, AI-facing APIs, REST’s origins, and versioned endpoints.

After this chapter you will be able to

What it builds on

Section by section

Introduction

This chapter introduction previews API contracts, REST and GraphQL, AI-facing APIs, REST’s origins, and versioned endpoints.

Introduction

Introduces APIs as public interfaces that let outside consumers use a protected domain core, and defines API-driven architecture as integration between services through APIs.

Key terms: Domain Core, Ports, Public Interface, API, Public Contract, consumers, API-Driven Architecture, API-Based Architecture, API-Driven Development, service boundaries

6.2 The Client-Server Model

This section defines the client-server split and explains why communicating across its network boundary is more costly than an in-memory call.

Key terms: Client-Server Model, Client, Server, Network Boundary, latency, failure, complexity

6.2.1 The Cost of Crossing the Line

Crossing the client-server boundary trades the speed and reliability of an in-memory call for the reach and scale of a network request.

Key terms: boundary, in-memory function call, network request, scale and reach, point of failure

6.2.2 The Separation of Duties

This section divides client and server responsibilities and explains why a clear boundary makes systems easier to maintain and scale.

Key terms: Client, Server, Presentation, Input Validation, Business Logic, Separation of Concerns, contract, maintain, scale

6.2.3 The Anatomy of the Conversation (Request/Response)

Explains how a client-server request and response work, why synchronous communication need not mean synchronous work, and how stateless requests support scaling.

Key terms: Request-Response Cycle, Request, Processing, Response, Rendering, Synchronous Communication, Asynchronous Flow, 202 Accepted, Blocking Chain, Statelessness

6.2.4 The "Clarity" Tradeoff: Thick vs. Thin Clients

This section compares thin and thick clients and explains why fast client-side feedback should be paired with server-side enforcement of critical business rules.

Key terms: Thin Client, Server-Side Rendering, round-trip, Thick Client, Single Page Apps, Mobile Apps, JSON, UI state, Critical Business Rules, Fast feedback

6.2.5 Why We Split Them (Scale and Specialization)

This section explains why separating clients from servers is worth the network costs: it supports scaling and lets specialized teams work independently.

Key terms: Client-Server model, Monolith, Horizontal Scaling, Frontend Engineers, Backend Engineers, Contract, API

6.3 API as a Public Contract

This section frames an API as a client-server commitment and explains why publishing it limits the changes its provider can safely make.

Key terms: API, public contract, Client, Server, REST, GraphQL, published contract, dependent services, breaking change

6.3.1 The "Restaurant Menu" Analogy

The restaurant-menu analogy shows how an API defines what clients can request while hiding the server’s internal workings.

Key terms: Kitchen, Server, Customer, Client, Menu, API, Decoupling, contract

6.3.2 The Clauses of the Contract

This section defines the four clauses of an API contract and explains why idempotency makes retries safe when network responses are lost.

Key terms: Endpoint, Headers, Request Body, Response Body, Status Codes, Redirect, Idempotency, network boundary, no-op

6.3.3 The "Breaking Change" Nightmare

This section explains why published APIs are difficult to change and distinguishes breaking changes from changes existing clients can ignore.

Key terms: contract, API endpoint, consumer, breaking change, Non-Breaking Change, required parameter, optional parameter, response field

6.3.4 Hyrum's Law: The Hidden Contract

Explains why clients may depend on undocumented API behavior and why changing that behavior requires a formal versioning strategy.

Key terms: Hyrum’s Law, Public Contract, observable behaviors, formal versioning strategy

6.3.5 The Escape Hatch: Versioning

Explains how API versioning lets a public contract evolve without breaking existing clients, and compares URI-path and date-based approaches.

Key terms: Versioning, URI Path Versioning, v1, v2, public contract, Date-Based Versioning, release date header, API Gateway, Middleware, backward-compatibility transformations

6.4 REST or GraphQL

Introduces REST and GraphQL as alternative HTTP styles for exposing an API contract and frames the choice as an engineering tradeoff.

Key terms: REST, GraphQL, Public Contract, endpoints, targeted querying

6.4.1 REST: The Vending Machine

This section explains REST’s resource-based contract, its over-fetching tradeoff, and how HTTP verb choices make retries safe or unsafe.

Key terms: REST, Resource, URL, over-fetching, field filtering, idempotency, GET, PUT, DELETE, POST

6.4.2 GraphQL: The Personal Shopper

This section explains GraphQL’s precise client-selected responses, the retry risk of mutations, and the tradeoffs that shape when to use GraphQL, REST, or gRPC.

Key terms: GraphQL, over-fetching, Personal Shopper, HTTP POST, query, mutation, idempotent, Idempotency Key, UUID, REST

6.4.3 Making The Defensible Decision

Uses the Chip Inventory example to choose an API style based on its consumers, document the tradeoff, and tailor APIs for different frontends.

Key terms: Napkin Sketch, REST, GraphQL, round-trips, chatty, Architecture Decision Record, ADR, RESTful API, HTTP caching, OpenAPI

6.5 Designing for the New User: The AI Agent

This section explains why AI agents as API consumers make clear API documentation and design more important.

Key terms: APIs, LLMs, AI Agents, API documentation

6.5.1 The "Dumb Genius" Paradox

This section explains why APIs for AI agents need explicit language and focused responses: agents can reason well but lack implicit context, and unnecessary data consumes limited context and money.

Key terms: AI Agent, Genius Intern, hallucinate, Context Window, tokens, Granularity, Convenience

6.5.2 Naming IS Prompt Engineering

This section explains how clear API names and explicit values guide LLM callers and reduce harmful guesses.

Key terms: API Schema, System Prompt, endpoint names, field names, Hallucination Hazard, Data Transfer Object (DTO), reasonType, string Enum, magic number, prompt engineered

6.5.3 The Modern Architect's AI Rule

This section explains how clear API specifications help AI agents choose the right tools and avoid unnecessary calls.

Key terms: API Specification, OpenAPI/Swagger, User Interface for the Robot, XML comments, Rules of Engagement, digital items, OpenAPI specs, server stubs, AI tool definitions, same source of truth

6.6 Diagram: Client-Server

The section uses a client-server diagram to show the API contract as the boundary between an outside client and a controlled server.

Key terms: Client, Server, Contract (API), API Gateway, rate limiting, security

6.7 Code Snippet: API Endpoint

This section explains how a clean API controller translates between HTTP and application code without taking on business logic.

Key terms: Controller, HTTP, JSON, Service, Routes, Status Codes, MVC, Model-View-Controller, View, Web APIs

6.7.1 Why This Matters

This subsection explains how a translating controller keeps business logic independent of the web, while warning that a clean API endpoint can conceal database performance problems.

Key terms: Controller, Translator, Primary Adapter, Core, Service Interface, Port, Object-Relational Mappers (ORMs), public endpoints, interface contracts, database performance traps

6.8 The Hidden Costs of Abstraction

This section introduces the tradeoff that clean abstractions make an API easier for clients to use while potentially hiding costs on the server.

Key terms: Abstraction, Contracts, Client, Server

6.8.1 The Hidden Performance Trap: The N + 1 Problem

This section explains how N+1 database queries arise in REST and GraphQL implementations, how each can avoid them, and why API performance must be checked at the database level.

Key terms: N+1 Query Problem, parent items, child item, Object-Relational Mapper, ORM, lazy loading, eager loading, Include, JOIN, GraphQL

6.8.2 The Hidden Governance Trap: API Sprawl

This section explains how accumulating feature-specific API endpoints creates a hard-to-manage public contract and recommends generalization and pruning instead.

Key terms: API Sprawl, endpoints, Clean Contract, Generalization, filtering capabilities, prune

6.8.3 The Hidden Knowledge Trap: Debugging Hell

This subsection explains why database abstractions can create a debugging skill gap and why developers still need SQL fundamentals.

Key terms: Skill Gap, Black Box, raw SQL, INDEX, JOIN, execution plans

6.8.4 The Hidden Availability Trap: Chained Dependencies

This section shows how a synchronous API call chain increases latency and makes order placement depend on every service, then illustrates moving noncritical shipping-label work to a queue.

Key terms: Coupling, Distributed Monolith, Latency Math, Availability Math, Synchronous, Asynchronous, Queue, Print Label

6.9 The Dork Side: The “Accidental Genius” Of REST

This section contrasts heavyweight late-1990s distributed-system protocols with the growing Web and explains that Roy Fielding described why the Web worked rather than inventing a new technology.

Key terms: SOAP, CORBA, World Wide Web, Roy Fielding

6.9.1 Dungeons and Dragons Trivia Time

This section introduces REST as Fielding’s architectural style for web applications and explains the resource model and constraints it uses.

Key terms: REST, architectural style, Resources, URL, GET, POST, Client-Server, Statelessness, Cacheability, Uniform Interface

6.9.2 Why "State Transfer"?

This subsection explains “state transfer” as shifting responsibility for holding application state from the server to the client so the server can scale.

Key terms: State, Server-Side State, Representation

6.9.3 The "Lost Ark" of REST: HATEOAS

Explains HATEOAS as a REST approach in which response links tell clients which actions are currently available.

Key terms: HATEOAS, Hypermedia, Application State, Client, Server

6.9.4 Leveling Up: The Richardson Maturity Model

Introduces the Richardson Maturity Model as a way to grade how RESTful an API is and contrasts strict Level 3 expectations with a pragmatic acceptance of Level 2.

Key terms: Richardson Maturity Model, RESTful, Level 2, Level 3

6.9.5 The Historical Takeaway

The section explains why REST’s design intent matters more than implementing every feature associated with it.

Key terms: HATEOAS, Statelessness, Cacheability, resilience, scalability

6.10 "In-Action": Defining an API Contract

A to-do list scenario introduces the architectural choice to define an API contract before writing code.

Key terms: Clarity Engineer, Contract, To-Do List

6.10.1 The "Function" Mindset (The Anti-Pattern)

This subsection critiques a function-style API whose verb-based URLs and string-only responses make operations redundant, ambiguous, and hard to extend without breaking clients.

Key terms: Function Thinker, verbs in URLs, ID, extensibility, breaking clients

6.10.2 Exercise: The Contract Challenge

This exercise asks the reader to turn a function-style UserProfile API into a resource-based contract, then notes that request-response communication still makes clients wait on servers.

Key terms: UserProfile, RESTful Contract, Resource, HTTP method, JSON object, Function Mindset, Request-Response Boomerang, REST, GraphQL

6.11 Checklist

This checklist reviews key API-design ideas from the chapter, including public contracts, retry safety, and the controller’s role.

Key terms: API, Public Contract, Breaking Changes, Idempotency, Safety Clause, network retries, PUT, DELETE, idempotencyKey, Controller

6.12 Recap

Recaps how client-server boundaries, reliable API contracts, and API design choices affect communication with human and AI consumers.

Key terms: Client-Server Model, Network Boundary, Synchronous Communication, Asynchronous Flow, Blocking Chains, Statelessness, Idempotency, Public Contract, versioning, Idempotency Key

Where this is used later

Concepts explained in this chapter

← Chapter 5: Hexagonal Architecture: Protecting the Core: The Power of Ports and Adapters Chapter 7: Event-Driven Architecture (EDA): Temporal Decoupling and Asynchronous Communication →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.