Create a service contract evolution policy: compat rules, consumer-driven tests, and…
- User
Create a service contract evolution policy: compat rules, consumer-driven tests, and deprecations.
- Assistant
Service Contract Evolution Policy
1. Purpose
This policy governs the evolution of service contracts (APIs, schemas, protocols) in our ecosystem to ensure reliability, backward compatibility, and smooth transitions for consumers. It emphasizes:
- Backward compatibility as the default.
- Consumer-driven contract testing (CDT) to validate expectations.
- Structured deprecation for unavoidable breaking changes.
All teams must adhere to this policy. Changes violating it require approval from the Architecture Review Board (ARB).
2. Compatibility Rules
Service contracts must maintain semantic versioning (MAJOR.MINOR.PATCH) and follow these rules for compatibility:
2.1 Backward-Compatible Changes (No Version Bump Required)
These can be released in MINOR or PATCH releases without consumer impact:
Category Allowed Examples Additions ✅ Add new fields, endpoints, headers, or query params (with defaults for old consumers). - Add optional field to JSON response.- New endpoint /v1/users/{id}/profile.Fields/Params ✅ Make required fields optional.✅ Add enum values. - Change required: truetofalsein schema.Responses ✅ Expand error codes/messages.✅ Increase response payload size limits. - Add new error code 429_RATE_LIMITED.Documentation ✅ Improve docs, add examples. - Update OpenAPI spec with better descriptions. 2.2 Breaking Changes (Require MAJOR Version Bump)
These must not be made in the active contract version:
Category Not Allowed Mitigation Removals ❌ Remove fields, endpoints, headers, enum values. Deprecate first (see Section 4). Types ❌ Change field types (e.g., string → int).❌ Change array → object. Use new field with old as alias. Semantics ❌ Change default values.❌ Alter request/response meanings.❌ Tighten validation (e.g., minLength increase). Announce + deprecate. Behavior ❌ Change authentication/authorization.❌ Modify pagination logic. New endpoint/version. 2.3 Versioning Strategy
- Path-based versioning:
/v1/users→/v2/users. - Header-based:
Accept: application/vnd.example.v2+json. - New major version for breaking changes; support old version for at least 12 months.
- Query param fallback:
/users?version=2(last resort).
Enforcement: All PRs must pass compatibility checks (e.g., OpenAPI diff tools like Spectral or Praxis).
3. Consumer-Driven Tests (CDT)
Consumers define and own contract expectations using Pact (or equivalent like Spring Cloud Contract).
3.1 Workflow
-
Consumer Side:
- Write Pact files defining interactions (requests/responses).
- Publish to shared Pact Broker (e.g.,
pact-broker.example.com).
-
Provider Side:
- CI/CD runs
pact-verificationagainst consumer pacts. - Fail deployment if contracts break.
- CI/CD runs
-
Implementation Requirements:
Step Responsibility Tooling Define contracts Consumer teams Pact JS/Ruby/Java library. Verify on deploy Provider CI pact-provider-verifier.Tag releases Both pact-broker publish --consumer-version-tags.Matrix testing Providers Test against multiple consumer versions. -
Best Practices:
- Consumers: Mock providers locally during development.
- Providers: Auto-generate tests from OpenAPI + consumer pacts.
- Threshold: 100% pact coverage for critical paths.
- Alerts: Slack/Email on pact failures.
Mandate: All public APIs must have CDT coverage >90% within 3 months of this policy.
4. Deprecations
Breaking changes must be deprecated gracefully with a minimum 6-month notice (12 months for major features).
4.1 Deprecation Process
-
Announce:
Channel Details Changelog CHANGELOG.md+ GitHub release notes.Docs Mark as "Deprecated" in OpenAPI spec. Headers Deprecation: 2025-06-01, sunsetting-v1-users-endpoint. -
Timeline:
Phase Duration Actions Deprecate Immediate Warn via header (e.g., Warning: 299 "Deprecated"). Log usage.Warn 3-6 months Dashboard metrics; consumer notifications. Freeze 6-12 months Read-only; no new features. Remove After notice MAJOR version bump; delete. -
Usage Tracking:
- Providers: Emit metrics (e.g., Prometheus:
api_deprecated_endpoint_usage_total). - ARB: Reviews metrics before removal.
- Providers: Emit metrics (e.g., Prometheus:
-
Exceptions:
- Security fixes: Immediate removal with 30-day notice.
- Approval: ARB waiver for <6 months.
4.2 Templates
- OpenAPI Deprecation:
deprecated: true deprecationMessage: "Use /v2/users instead. Removal: 2025-06-01." - HTTP Header:
Warning: 299 "Deprecated endpoint /v1/users. Migrate to /v2/users by 2025-06-01"
5. Responsibilities & Enforcement
Role Duties Service Owners Implement CDT, follow compat rules, handle deprecations. Consumers Maintain pacts, migrate off deprecations. ARB Approves exceptions, reviews metrics. Platforms Enforce via CI gates (e.g., GitHub Actions). Violations: Block merges; escalate to CTO.
6. Tools & Resources
- Contract Testing: Pact Broker (self-hosted).
- Diffing: OpenAPI Diff, API Compat Checker.
- Monitoring: Datadog/Grafana for deprecation metrics.
- Repo:
docs/service-contract-policy.md.
Last Updated: 2023-10-01. Review annually.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.