Contracts and compatibility
A contract records the shape an API operation promises. Echo keeps its method, path, document and published versions together. A mock can generate data from a contract, and an application can bind to a version to declare its dependency. Publishing a contract does not deploy or test a running API.
Create and publish
Open Contracts in Maestro, create the contract and open Publish version. Paste an Echo contract document and review it before publishing. This field expects Echo document JSON, not an example response or an unconverted JSON Schema. Schema conversion is available in the mock route editor.
Published versions are numbered snapshots. An application's binding records its agreed version. The web diff shows changed paths, reasons and separate consumer and producer verdicts. Reusing previously published content can return an existing, older version instead of creating another one.
Read the right direction
A Consumes binding means the application calls the operation. Provides means it supplies it. The comparison distinguishes request changes from response changes and assesses each side.
| Change | Consumer | Producer |
|---|---|---|
| Add an optional request field | Safe | Safe |
| Add a required request field | Breaking | Breaking |
| Add a required response field | Safe | Breaking |
| Remove a response field or change its type | Breaking | Breaking |
| Add an optional response field | Conditional | Safe |
These are the current classifier's verdicts. An extra optional response field is conditional because JsonUnmappedMemberHandling.Disallow rejects unknown fields. Read the condition and reason in the diff. Safe means no incompatibility was found for that side; Warning calls for review; Breaking identifies an incompatibility; ConditionalBreaking depends on the named condition. An unknown verdict is not approval.
Review before accepting
A producer can publish through EchoContractPublicationClient in Gapfy.Echo.Contracts. Create the contract and its Provides binding first, then use a key with PublishOwnedContracts. The client publishes an owned contract's version; it neither creates contracts nor takes ownership.
Publishing completes before compatibility results are returned. A breaking verdict does not undo publication. Review the differences before changing a consumer or accepting a new baseline.
Gapfy.Echo.Testing compares consumed contracts with reviewed snapshots in your repository. It can fail CI when a change breaks that consumer. It does not test the running API or validate the contracts your application provides.
Next steps
Connect your application with applications and keys, or use the document to serve remote mocks.