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. Creating, publishing and comparing contracts in Maestro are available on Echo Free. 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.

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. Issuing that application key and managing the binding require a paid Echo plan and Echo/ManageHosting, which the organization administrator receives by default on that plan. 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.

Build a response contract in the desktop

Open a mock route and choose Contract response mode. Start from a JSON example, inspect the inferred tree and review any ambiguities before saving. Select a field to choose a supported generator, then check the previews with a representative request path. A saved example is a starting point; it does not describe every possible response automatically.

Add named scenarios for cases such as an empty result or a rejected operation. Give each scenario its own example and select it to inspect the generated response. Send X-Echo-Scenario: empty to request a scenario named empty; omit the header for the default response. X-Echo-Seed lets you repeat random generation. A fixed seed does not freeze generators that use the current date. A route pinned to a published contract version cannot edit that version in place.

Import models without rewriting them

With a signed-in account and a connection, open Import and export models in the desktop contract editor.

1. Choose C#, TypeScript, JavaScript, Java, Python or JSON Schema.
2. Paste source or open the related files together. Include referenced types and provide the root type when several types are present.
3. For C#, choose whether property names use camelCase. Explicit JSON property names take precedence.
4. Preview the conversion. Read the generated document, schema and diagnostics before applying.
5. Apply the successful preview to the route. Closing the dialog or a failed conversion leaves the route unchanged. Editing the input requires a new preview.

Use the example for the selected language if you want to check the expected structure before importing your own model.

Conversion reads source without executing it. Missing dependencies and unsupported constructs produce diagnostics. Runtime JavaScript values are not enough to infer a complete model. Custom serializers, polymorphism and recursive structures may need an explicit supported schema. Imported schemas stay attached to the contract when you edit the route's example or path; update their structure through import rather than replacing individual generators.

Export models for another application

Choose the output language and export the current contract. Inspect the generated files, copy one or save the full ZIP, which includes contract.schema.json. The same six formats are available for export. Exporting reads the current document and does not publish another version.

Review diagnostics about number precision and missing versus null fields. Generated types alone do not enforce every range, enum or extra-property rule; retain schema validation where your application needs those checks. Python exports include from_dict and to_dict; Decimal values need an appropriate JSON encoder.

Next steps

Connect your application with applications and keys, or use the document for public mock hosting.