Skip to content

CONCEPT Cited by 2 sources

Contract-first design

Definition

Contract-first design = defining the API contract (endpoints, request/response shapes, error codes, auth) before any implementation, typically in a machine-readable schema language such as OpenAPI / GraphQL SDL / Smithy / Protobuf. Generators produce server stubs, client SDKs, mock servers, and documentation from the contract; both sides code against the same frozen surface.

Why agentic development needs it

Named by the 2026-03-26 AWS Architecture Blog post as a precondition for end-to-end validation by an AI agent while sibling services are still being built:

"When combined with contract-first design — where APIs are defined upfront using OpenAPI specifications — agents can validate integrations even before all services are implemented."

The property the agent exploits: the contract is executable enough that a mock server can answer from it. The agent writes a client, points it at the contract-generated mock, validates request shape and parses responses — all without waiting for the real dependency to ship.

Canonical artefacts

  • OpenAPI — REST, the most common choice; AWS post names it specifically.
  • GraphQL SDL — schema-first GraphQL.
  • Smithy — AWS's service-modeling IDL (code-gen for SDKs, server stubs, docs).
  • Protobuf + gRPC — RPC contract-first default.

Pairs with

Seen in

Last updated · 542 distilled / 1,571 read