Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

API

Pattern

A reusable solution you can apply to your work.

Also known as: Application Programming Interface

“A good API is not just easy to use but hard to misuse.” — Joshua Bloch

Understand This First

  • Determinism – consumers expect API calls with the same inputs to produce predictable results.

Context

At the architectural level, no useful piece of software exists in total isolation. Programs need to talk to other programs, to request data, trigger actions, or coordinate work. An API is the agreed-upon surface where that conversation happens. It defines what you can ask for, what format to use, and what you’ll get back.

APIs are everywhere: a weather service exposes an API so your app can fetch forecasts; a payment processor exposes an API so your checkout page can charge a card; an operating system exposes APIs so programs can read files and draw windows. In agentic coding, APIs are particularly central because AI agents interact with the world primarily through tool calls, and every tool is, at its core, an API.

Problem

Two software components need to work together, but they’re built by different people, at different times, possibly in different programming languages. How do they communicate without each needing to understand the other’s internal workings? And how do you make that communication reliable enough to build on?

Forces

  • Abstraction vs. power: A simpler API is easier to learn but may not expose everything a sophisticated consumer needs.
  • Stability vs. evolution: Changing an API can break every consumer that depends on it, but freezing it forever prevents improvement.
  • Convenience vs. generality: An API tailored to one use case is delightful for that case but awkward for others.
  • Security vs. openness: Every API endpoint is a potential attack surface, but restricting access too much makes the API useless.

Solution

Design a clear boundary between the provider (the system that does the work) and the consumer (the system that asks for it). The API specifies the contract: what operations are available, what inputs each operation expects, what outputs it returns, and what errors can occur.

Good APIs share several qualities. They’re consistent: similar operations work in similar ways. They’re minimal: they expose what consumers need and hide what they don’t. They’re versioned: so changes don’t silently break existing consumers. And they’re documented: because an API without documentation is a guessing game.

The most common pattern for web APIs today is REST (using HTTP verbs like GET and POST on URL paths), but APIs also take the form of library functions, command-line interfaces, GraphQL endpoints, or gRPC services. The shape varies; the principle is the same: define a stable surface for interaction.

When directing an AI agent, you’ll frequently ask it to consume APIs (calling a third-party service) or produce them (building an endpoint for others to call). Understanding what makes an API well-designed helps you evaluate whether the agent’s work will be maintainable and secure.

How It Plays Out

You ask an agent to integrate a third-party mapping service into your application. The agent reads the service’s API documentation, constructs the correct HTTP requests, handles authentication, and parses the responses. If the API is well-designed, this goes smoothly. If it’s poorly documented or inconsistent, even the agent will struggle, and you’ll spend time debugging mysterious failures.

A team builds a backend service and needs to expose it to a mobile app. The agent generates a REST API with endpoints like GET /users/{id} and POST /orders. The team reviews the design: Are the URL paths intuitive? Are error responses consistent? Is authentication required on every endpoint? These are API design questions, not implementation details.

Tip

When an AI agent generates an API, check for consistency: do similar operations follow the same naming, parameter, and error conventions? Inconsistency in an API creates confusion that compounds over time.

Example Prompt

“Design a REST API for our task management service. Define endpoints for creating, listing, updating, and deleting tasks. Use consistent naming, include error response shapes, and document the authentication requirement for each endpoint.”

Consequences

A well-designed API lets different teams, systems, and AI agents collaborate without tight coupling. It becomes a stable contract that both sides can rely on. Software built on clean APIs is easier to extend, test, and replace piece by piece.

The cost is that API design is hard to change after consumers depend on it. A poorly designed API becomes technical debt that affects every system connected to it. And every public API is a security surface that must be defended (see Protocol for the rules governing how interactions unfold over that surface).

  • Refined by: Protocol — a protocol governs the rules of interaction over time; an API defines the surface where interaction happens.
  • Uses: Side Effect — API calls often trigger side effects (writing data, sending emails) that consumers must understand.
  • Enables: Event — many APIs use event-based patterns (webhooks, message queues) alongside request-response.
  • Depends on: Determinism — consumers expect API calls with the same inputs to produce predictable results.