Index of every page on this site: llms.txt
All skills
jeremylongshore avatar

/validating-api-contracts

@820dfc8
Run it yourself

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".

Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/validating-api-contracts

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈66 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈3.3k more on demand in 6 files.

Description uses 3.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈264 characters, or 3.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
  6. For schema-based validation (non-Pact):
    • Compare OpenAPI spec versions using openapi-diff to detect breaking changes.
    • Flag removed endpoints, changed parameter types, and narrowed response schemas.
    • Run schema validation tests against the actual API responses.
  7. Integrate contract tests into the CI/CD pipeline for both consumers and providers.

Output

  • Consumer Pact test files defining expected API interactions
  • Generated Pact contract files (JSON) in pacts/ directory
  • Provider verification test configuration
  • Pact Broker deployment with published contracts and verification status
  • CI pipeline integration with can-i-deploy deployment gates
  • Contract evolution report flagging breaking vs. non-breaking changes

Error Handling

Error Cause Solution
Provider verification fails Provider response does not match consumer expectations Check if the contract is outdated; update consumer tests if the change is intentional; fix provider if regression
can-i-deploy blocks release Consumer has unverified or failed contracts Run provider verification; check if the right version tags are published; verify Pact Broker webhook fired
Pact Broker connection error Broker URL or credentials misconfigured Verify PACT_BROKER_BASE_URL and PACT_BROKER_TOKEN environment variables; check network connectivity
Provider state not found Consumer test references a state the provider does not implement Add the missing provider state setup function; align state names between consumer and provider
Too many contracts to maintain Every consumer-provider pair has extensive contracts Focus on critical interactions; use matchers instead of exact values; consolidate similar interactions

Examples

Pact consumer test (JavaScript):

import { PactV4 } from '@pact-foundation/pact';

const provider = new PactV4({ consumer: 'Frontend', provider: 'UserAPI' });

describe('User API Contract', () => {
  it('fetches a user by ID', async () => {
    await provider
      .addInteraction()
      .given('user with ID 1 exists')
      .uponReceiving('a request for user 1')
      .withRequest('GET', '/api/users/1', (builder) => {
        builder.headers({ Accept: 'application/json' });
      })
      .willRespondWith(200, (builder) => {  # HTTP 200 OK
        builder
          .headers({ 'Content-Type': 'application/json' })
          .jsonBody({
            id: like('1'),
            name: like('Alice'),
            email: like('alice@example.com'),
          });
      })
      .executeTest(async (mockServer) => {
        const response = await fetch(`${mockServer.url}/api/users/1`);
        const user = await response.json();
        expect(user.name).toBeDefined();
      });
  });
});

Provider verification test:

import { Verifier } from '@pact-foundation/pact';

describe('User API Provider Verification', () => {
  it('validates consumer contracts', async () => {
    await new Verifier({
      providerBaseUrl: 'http://localhost:3000',  # 3000: 3 seconds in ms
      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
      provider: 'UserAPI',
      publishVerificationResult: true,
      providerVersion: process.env.GIT_SHA,
      stateHandlers: {
        'user with ID 1 exists': async () => {
          await db.users.create({ id: '1', name: 'Alice', email: 'alice@example.com' });
        },
      },
    }).verifyProvider();
  });
});

can-i-deploy CI check:

pact-broker can-i-deploy \
  --pacticipant Frontend \
  --version $(git rev-parse HEAD) \
  --to-environment production \
  --broker-base-url $PACT_BROKER_URL \
  --broker-token $PACT_BROKER_TOKEN

Resources

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo3 checks · Risk MEDIUM
  • Gen Agent Trust Hub2mo

    The skill provides tools for API contract testing but includes a script that dynamically generates and executes shell scripts from input, which is a security risk. It also processes external API definitions that could be used for indirect prompt injection.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 820dfc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 20 hours ago.

Activeupdated 3 months ago
What it can do
Reads files Edits files Runs commands
version
1.24.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
[
  "testing",
  "api",
  "validating-api"
]
All 6 allowed tools
ReadWriteEditGrepGlobBash(test:contract-*)
Other metadata
compatibility
Designed for Claude Code

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/validating-api-contracts