validating-api-contracts

name	validating-api-contracts
description	Validate API contracts using consumer-driven contract testing (Pact, Spring Cloud Contract). Use when performing specialized testing. Trigger with phrases like "validate API contract", "run contract tests", or "check consumer contracts".
allowed-tools	Read, Write, Edit, Grep, Glob, Bash(test:contract-*)
version	1.24.0
author	Jeremy Longshore <[e-mail]>
license	MIT
tags	["testing","api","validating-api"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Contract Test Validator

Overview

Validate API contracts between services using consumer-driven contract testing to prevent breaking changes in microservice architectures. Supports Pact (the industry standard for CDC testing), Spring Cloud Contract (JVM), and OpenAPI-diff for specification comparison.

Prerequisites

• Contract testing framework installed (Pact JS/Python/JVM, or Spring Cloud Contract)
• Pact Broker running (or PactFlow SaaS) for contract storage and verification
• Consumer and provider services with clearly defined API boundaries
• Existing integration points documented (which consumers call which provider endpoints)
• CI pipeline configured for both consumer and provider repositories

Instructions

1. Identify consumer-provider relationships in the system:
   • Map which services call which APIs (e.g., Frontend calls User API, Order API calls Payment API).
   • Document each interaction: HTTP method, path, headers, request body, expected response.
   • Prioritize contracts for the most critical and frequently changing integrations.
2. Write consumer-side contract tests (Pact consumer tests):
   • Define the expected interaction: method, path, query parameters, headers, request body.
   • Specify the expected response: status code, headers, and response body structure.
   • Use matchers for flexible assertions (like(), eachLike(), term()) instead of exact values.
   • Generate a Pact file (JSON contract) from the consumer test.
3. Publish consumer contracts to the Pact Broker:
   • Run pact-broker publish with the consumer version and branch/tag.
   • Enable webhooks to trigger provider verification when new contracts are published.
   • Configure can-i-deploy checks in CI to gate deployments.
4. Write provider-side verification tests:
   • Configure the Pact verifier to fetch contracts from the Pact Broker.
   • Set up provider states (test data scenarios matching consumer expectations).
   • Run verification against the actual provider implementation.
   • Publish verification results back to the Pact Broker.
5. Handle contract evolution:
   • Adding new fields: Safe -- consumers using matchers will not break.
   • Removing fields: Breaking -- coordinate with all consumers before removal.
   • Changing field types: Breaking -- requires consumer updates first.
   • Use can-i-deploy to check compatibility before releasing either side.