Building Software

Engineering Fundamentals for the Agent Era

Contents Section 6, Design

Interfaces and APIs

Mistakes to catch in review

  1. A breaking change to a public API, such as a renamed field or changed type, shipped without a version or a migration path.

  2. A list endpoint with no pagination or limit that works in development and times out on real data.

  3. Error responses whose shape differs from one endpoint to the next, or that leak stack traces to clients.

Designing the contracts between parts of a system and between systems: shapes, errors, versions and limits.

Topics

API Design
Resources, operations and naming that match the domain and are hard to misuse.
Error Contracts
Consistent error shapes and codes that tell callers what went wrong and whether a retry could help.
Versioning and Compatibility
Adding without breaking, deprecating deliberately, and knowing who depends on what.
Pagination, Filtering and Limits
Bounding every response and every request so no caller can ask for everything at once.
Schemas as Contracts
Machine-readable definitions, such as OpenAPI, JSON Schema or protocol buffers, that validate data and generate code.

You understand it when you can

  • Design the API for a small resource, including errors, pagination and versioning.
  • Decide whether a proposed change is backward compatible for existing clients and explain why.
  • Write a schema for an API and generate a client or a validator from it.

Drill

While fixing a typo, an agent renamed the user_name field to username in a public API response, and in the same change added a GET /orders endpoint that returns every order in one response. Find which clients break, what the endpoint does for your largest account, and how each change should have shipped.

Start here

Watch

How To Design A Good API and Why it Matters

Joshua Bloch, 2007. 60-minute talk.

Bloch's rules for APIs that are easy to use and hard to misuse: 'when in doubt leave it out', public APIs are forever, and names and failure behavior are part of the contract. These apply directly to REST and RPC design.

Watch

API Evolution without Versioning

Brandon Byars, 2023. 49-minute talk.

Byars covers the ways an API can change without breaking existing clients, the trade-off between elegance and stability, and when a versioned break is justified. This is the missing thinking behind renaming user_name to username.

Read

API Design Patterns

JJ Geewax, 2021.

Distilled from Google's API design guidance: resource naming, standard methods, pagination with page tokens, field masks and versioning, each with the failure it prevents.

The Design of Web APIs

Arnaud Lauret, 2025, 2nd edition.

Takes a REST API from requirements to an OpenAPI description, with chapters on error design, handling non-backward-compatible changes and versioning, and standardizing design decisions.

Principles of Web API Design: Delivering Value with APIs and Microservices

James Higginbotham, 2021.

An outside-in method for mapping domain operations to resources and choosing among REST, gRPC, GraphQL and async styles, including how to document the contract before building it.

Primary sources

  • RFC

    RFC 9457: Problem Details for HTTP APIs

    The IETF standard for one consistent machine-readable error body (type, title, status, detail, instance). It answers the problem of error shapes that change from endpoint to endpoint.

  • Reference

    Google API Improvement Proposals (AIPs)

    Google's public API design rules, with individual AIPs on pagination, errors, and backwards compatibility that define what counts as a breaking change.