Module 04Term 1 · Foundations4 poster items

APIs and Contracts

Sign in to save your progress across devices. Until then it is kept in this browser.

Why this matters

An API is a promise. Once a mobile app, a partner or an agent depends on it, every change can break someone you cannot see. Enterprise buyers judge you by the quality of your API contracts.

Learning outcomes

  1. Design consistent REST APIs with an OpenAPI contract.
  2. Make every mutating endpoint idempotent.
  3. Version APIs and libraries without breaking clients.
  4. Know when gRPC is the right tool.

Lessons

4.1 Contract-first design

  • Write the OpenAPI spec first; generate types, clients, docs and mock servers from it.
  • Consistent conventions: nouns for resources, plural paths, standard status codes, cursor pagination, ISO 8601 timestamps.
  • One error format everywhere (RFC 9457 Problem Details): type, title, status, detail, plus a request ID.
  • Validate every input against the schema at the boundary; reject unknown fields.
  • Never return more fields than needed (excessive data exposure is a classic API vulnerability).

4.2 Idempotency (14)

Networks fail after the server has done the work but before the client hears back. The client retries. Without idempotency, the customer is charged twice.

Pattern (as popularised by Stripe):

  1. Client sends Idempotency-Key: <uuid> on POST.
  2. Server stores key + request hash + response in a table with a unique constraint.
  3. Same key again: return the stored response, do not re-execute.
  4. Same key, different body: reject with 422.
  5. Expire keys after 24 hours or more.

GET, PUT and DELETE should be naturally idempotent. Design them so.

4.3 Versioning (102, 103)

  • API versioning: URL (/v1/) or header. Additive changes (new optional fields) are non-breaking; removing or renaming fields, changing types or semantics is breaking.
  • Deprecation policy: announce, add Deprecation and Sunset headers, measure usage of the old version, then remove.
  • Semantic versioning for packages: MAJOR.MINOR.PATCH. MAJOR breaks, MINOR adds, PATCH fixes. Pin dependencies with a lockfile; do not trust that others follow semver perfectly.

4.4 gRPC (100)

Typed, binary, fast, streaming, over HTTP/2. Great for internal service-to-service traffic at scale. Poor fit for browsers and public APIs. A solo founder rarely needs it; learn the concept.

4.5 API security preview

Authorization on every object (BOLA is the top API risk), rate limits per key, pagination limits, request size limits. Detailed in 05 · Application Security: OWASP Top 10:2025.

Lab 4: Ship a contract

  1. Write an OpenAPI spec for your core resource; generate a typed client.
  2. Add idempotency keys to your payment or "create order" endpoint; write a test that sends the same request 5 times concurrently and asserts one record.
  3. Make a breaking change the right way: release v2 alongside v1 with deprecation headers.
  4. Contract tests in CI fail if the implementation drifts from the spec.

Definition of Done

AI prompt pack

  • "Generate an OpenAPI 3.1 spec from these routes, then list inconsistencies in naming, status codes and error shapes."
  • "Add Stripe-style idempotency keys to this endpoint, backed by a Postgres table with a unique constraint. Handle the concurrent-duplicate case."