REL03-BP03 Provide service contracts per API
A service contract is a documented, machine-readable agreement between an API producer and its consumers. It defines the operations, data types, and fields that both sides rely on, so each can change its implementation without breaking the other. With a versioning strategy, consumers keep using the current API and migrate on their own schedule. Producers deploy whenever they are ready, and teams pick the technology stack that suits them.
Desired outcome:
-
Your services operate independently while sharing an integrated runtime dependency through a common contract.
-
Your producer and consumer changes do not interrupt the overall system as long as both sides honor the contract.
-
Your components release functionality, upgrade dependencies, or fail over to a disaster recovery (DR) site with little or no impact on each other.
-
Your services scale independently to absorb demand without requiring other services to scale with them.
Common anti-patterns:
-
Teams create APIs without strongly typed schemas, so bindings cannot be generated and payloads cannot be validated programmatically.
-
Teams adopt no versioning strategy, which forces consumers to update and release whenever a contract changes, or fail.
-
Error messages expose details of the underlying implementation instead of describing integration failures in the domain language.
-
Teams do not use contracts to build test cases or mock implementations, which prevents independent testing of components.
Benefits of establishing this best practice:
-
Distributed systems whose components communicate over contracts are more reliable.
-
Developers catch mismatches early through type checking that verifies requests and responses against the contract.
-
Each API has a clear, self-documenting interface.
-
Interoperability improves across different systems and programming languages.
Level of risk exposed if this best practice is not established: Medium
Implementation guidance
A service contract names the operations an API exposes and defines the data objects and fields for each request and response. With strong typing, tools generate client bindings and validate payloads automatically. Without a typed schema, integration errors occur only at runtime, often in production, and each consumer discovers them separately.
Contracts change over time. Extending a contract is the lighter option: you add optional fields or supply default values for new required fields, so existing consumers keep working. Extension suits JSON-based protocols such as REST and GraphQL. When a change is not backward compatible, you version the API instead. Proxy versioning places a facade in front of the service that maps requests and responses between versions, so the team maintains a single codebase. XML-based protocols such as SOAP need testing with consumers before you rely on extension, because consumer tolerance for added fields varies.
Because both sides agree on the interface, a consumer and a producer can release, upgrade, or fail over to a DR site independently, as long as neither breaks the contract. Amazon API Gateway fronts REST APIs, integrates with AWS and other web services, and supports the OpenAPI specification and versioning. AWS AppSync exposes a GraphQL endpoint defined by a schema that serves as the contract for queries, mutations, and subscriptions. Amazon EventBridge uses event schemas for asynchronous integrations and generates code bindings from them.
Implementation steps
-
Define the contract first: Before implementation, express the API's capabilities and define strongly typed data objects and fields for its input and output. A contract-first approach lets producers and consumers develop and test against the same agreement in parallel.
-
Manage REST contracts with Amazon API Gateway: Import an OpenAPI definition to create an API, and integrate it with infrastructure as code tools such as the AWS Serverless Application Model
and the AWS Cloud Development Kit (AWS CDK) (AWS CDK) . Export an API definition to give consumers and testing tools an integration specification. -
Define GraphQL contracts with AWS AppSync: Define a GraphQL schema to generate the contract interface and simplify access to complex REST models, multiple database tables, or legacy services. AWS Amplify
projects integrated with AppSync generate strongly typed client query files and a GraphQL client library for Amazon DynamoDB tables. -
Define event contracts with Amazon EventBridge: For asynchronous integrations, use event schemas from the schema registry or define your own with the OpenAPI specification. From a registered schema, generate client bindings so your code integrates with events in a type-safe way. See Amazon EventBridge code bindings.
-
Extend contracts before you version them: When you add capability, prefer extension by adding optional fields or default values for required fields, which keeps existing consumers working. JSON-based protocols such as REST and GraphQL suit extension well. Test XML-based protocols such as SOAP with consumers first to confirm that extension is feasible.
-
Version with a proxy facade when extension is not enough: For breaking changes, use proxy versioning so the underlying service keeps a single codebase. With API Gateway, use request and response mappings to supply defaults for new fields or strip removed fields between versions.
Resources
Related best practices:
Related documents:
Related videos:
Related examples:
Related workshops:
Related services: