liveBook · Manning

Contract

As explained in Build High Value Software Systems

An application programming interface is a defined set of operations and rules through which software components interact.

A contract makes expected behavior visible before implementation. For an API endpoint, it can define which responses callers may expect; for a feature, it can also set constraints and exclusions. That boundary gives developers, AI tools, and reviewers a way to distinguish requested behavior from plausible-looking additions. section 3.2.1 section 4.5.4 section 3.3.2

An order endpoint with a narrow contract

Suppose GET /orders/:id specifies 200 when an order exists and 404 when it does not. A generated handler may temporarily return 501 while its logic is unfinished; 501 is a scaffold signal, not a new contracted outcome. Failing tests for 200 and 404 then guide implementation. Adding 400, 409, or 422 responses, ID validation, caching, or a tax calculation calls for a decision rather than silent acceptance. section 3.2.1 section 3.3.2

Listing 3.1 Handler skeleton with no design decisions
export async function getOrder(req: Request, res: Response) {
  // TODO: Implement order retrieval logic
  // TODO: Handle 404 case when order not found
  res.status(501).json({ error: "Not implemented" });
}

The handler marks the two required behaviors as TODOs and returns a temporary 501 instead of inventing implementation details. section 3.2.1

Use the contract as a working boundary, not a claim that every decision is final:

  • Give a generator the contract and narrow instructions. Ask for disposable scaffolding or tests rather than an apparently complete implementation with unrequested behavior. section 3.2.1 section 3.6
  • In a pull request, expose the request, contract, and decisions. Ask where each added response, rule, or abstraction came from; passing tests alone cannot answer that question. section 3.3.2
  • Refine the contract when implementation reveals real constraints. A webhook specification, for example, can explicitly require built-in HMAC verification, a 200 response on internal errors, and no idempotency tracking in that handler. section 4.5.4

Contracts also cross team boundaries. If services settle on incompatible event formats, downstream consumers must build adapters. Some agreements are harder to see: retry behavior, eventual-consistency assumptions, and feature flags may shape an integration without appearing in one repository. Make shared formats and integration assumptions explicit, assign ownership for standards that affect multiple teams, and revisit them as the system changes. A contract is useful when it makes both implementation choices and their consequences visible. section 11.2.2 section 13.4.1

How Build High Value Software Systems covers it

How deep it goes
Works through endpoint responses, temporary scaffolding, review questions, refined constraints, and cross-team consequences; does not specify a formal contract language.
Examples
Uses a 200/404 order endpoint with a temporary 501 stub, a constrained payment webhook, and incompatible inter-service event formats.
What it assumes
Assumes familiarity with HTTP endpoints and pull requests while illustrating contract boundaries through response codes and review questions.
What you can do after
Practice/perform contract-guided scaffolding, testing, and review while questioning behavior that was not requested.
How it connects
Links contracts to test-driven development, pull-request review, AI-generated code, event formats, and service integration.

Also explained in

Compare how 58 books explain contract →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build High Value Software Systems. The section links point to the parts of the book it draws on.