Pin down the interface between two services
When two microservices talk, ambiguity is expensive: one team assumes a field is optional, the other makes it required, and the integration breaks in staging. An API contract removes that ambiguity by writing the interface down before the code exists. This builder generates a structured contract with schemas, error codes, an SLA, and a versioning policy.
How it works
You describe the endpoint and list the request and response fields with their types and required flags. The tool produces:
- Endpoint — method and path, plus the consumer and provider names.
- Request schema — a table of fields, and a sample JSON request built from your field definitions, using type-appropriate placeholder values.
- Response schema — the success body as a table and a sample JSON response.
- Error codes — the HTTP statuses the endpoint returns and what each means.
- SLA — latency and availability targets.
- Versioning policy — how breaking versus additive changes are handled.
Everything renders in your browser. The sample JSON is generated from your schema so it always matches the field list.
Tips and example
Keep contracts additive. Adding an optional field is safe; removing or renaming one is a breaking change that needs a new major version. State this explicitly so neither team is surprised.
Pick realistic SLA numbers your service can actually hit, for example p95 latency under 200ms and 99.9% availability, then design consumer timeouts above that with a retry budget. Document the failure mode too: a 503 with Retry-After is far kinder to consumers than a silent hang.
Treat the generated sample request and response as the seed for a consumer-driven contract test. Capturing the expected shapes in CI means either side drifting from the contract fails the build instead of an integration in production.
Common contract pitfalls and how to avoid them
Ambiguous nullability. A field listed as string leaves open whether it can be absent, null, or an empty string. Contracts should distinguish required string, optional string (may be absent), and nullable string (present but null) — especially for response fields that may be omitted in certain states. Spell this out explicitly in the field definitions to prevent deserialization errors.
Implicit error semantics. Most teams document the happy-path response and ignore errors until they occur in production. Map every error code your endpoint can realistically return: 400 with a validation-error body, 404 when the resource is not found, 422 for business-rule rejections, 503 when a downstream dependency is unavailable. Consumers need to know which errors are retryable and what the error body looks like.
Silent breaking changes. Renaming a field is a breaking change even if it is done inside a single major version. The safest approach is to add the new name alongside the old one, then deprecate the old one with an explicit sunset date in the contract. Remove it only after the consumer confirms they have migrated.
SLA numbers without context. “p95 under 200ms” is useful; “fast” is not. State the percentile (p95 or p99), the measurement point (at the provider’s load balancer), and the conditions under which the target applies (normal load, not a cold start). This prevents disputes about what “within the SLA” means when a consumer’s timeout fires.
When to write a contract vs. just sharing a schema
API schemas (OpenAPI, JSON Schema, Protobuf) capture the data shapes but leave out the SLA, the versioning policy, and the agreed error semantics. A contract goes further: it names the two parties, states mutual obligations, and forms the basis for automated contract tests. Contracts are most valuable when the consumer and provider are owned by different teams or different services with independent deploy schedules — exactly the common microservices scenario. For a single team owning both sides, a shared schema may be enough.