CONCEPT Cited by 1 source

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¶

patterns/ephemeral-preview-environments — preview environments hosting contract-generated mock servers so agents can integration- test before all services are deployed.
patterns/tests-as-executable-specifications — contract tests verify each side honors the agreed surface.

Seen in¶

sources/2026-03-26-aws-architecting-for-agentic-ai-development-on-aws — contract-first design named as complementary to preview environments for AI-agent integration validation.

concepts/schema-registry — runtime counterpart at the event-bus tier (EventBridge / Kafka).