api-contract-builder

name	api-contract-builder
description	Design and document API contracts including routes, request and response schemas, validation rules, error envelopes, auth expectations, naming conventions, and examples. Use when creating or revising endpoints, OpenAPI specs, or service interfaces.

Api Contract Builder

Overview

Define the contract before implementation details start to drift.

Core Workflow

1. Clarify the consumer, operation, and boundary: endpoint, event, internal service, or public API.
2. Define the request shape, required fields, validation rules, defaults, and auth expectations.
3. Define the response shape for success and failure, including stable error codes and messages.
4. Add examples that make the contract easy to adopt and test.
5. Check compatibility, naming consistency, pagination, idempotency, and versioning concerns.

Deliver

• Provide a contract that is implementation-ready.
• Include sample payloads and clear error cases.
• Call out open decisions that affect consumers or backward compatibility.

Guardrails

• Prefer explicit schemas over prose-only descriptions.
• Keep error shapes consistent across endpoints when the system already has a pattern.
• Flag breaking changes early rather than hiding them in a draft.