API Consumer Impact Analysis Prompt

This prompt is designed for API product managers, platform engineers, and developer relations teams who need a structured, evidence-based assessment of how a committed API schema change will affect downstream consumers. The core job-to-be-done is turning a raw schema diff and a consumer registry into a decision-support artifact that identifies which client integrations will break, which require a migration path, and the estimated effort for each affected consumer. Use this before communicating deprecations, during release planning, or as part of a change-advisory board review to ensure no consumer is blindsided by a breaking change.

To use this prompt effectively, you must provide two concrete inputs: a machine-readable schema diff (such as an OpenAPI or GraphQL diff) representing a committed change, and a consumer registry that maps client identifiers to their specific API surface usage (endpoints, fields, and methods). Without a reliable consumer registry, the analysis becomes speculative and loses its operational value. The output is a structured impact summary, not an automated enforcement gate. It is meant to inform human decision-making about rollout sequencing, deprecation windows, and direct consumer communication. The prompt works best when the schema change is finalized and the consumer registry is maintained as a source of truth, such as from API gateway logs, CDN metrics, or a developer portal's application registry.

Do not use this prompt when the schema diff is speculative, uncommitted, or part of an early design spike. It is also unsuitable when you lack a consumer registry or when the registry is so stale that it misrepresents actual usage. In high-risk domains such as payments, healthcare, or identity, always pair the output with a human review step before any external communication. The prompt is a force-multiplier for teams that already practice good API governance; it will not compensate for missing operational data or unclear ownership of the API surface. If you are unsure whether your inputs are production-grade, start by validating your consumer registry and schema diff independently before running this analysis.

This template is designed to be dropped directly into your AI orchestration layer—whether that's a Python script, a LangChain node, an API gateway plugin, or a CI/CD pipeline step. It expects a structured diff between two API schema versions and produces a consumer-facing impact summary that identifies which client integrations break, which need migration, and what the estimated effort looks like. Every placeholder is wrapped in square brackets so you can replace them with real values at runtime without confusing the model's own output formatting.

textCopy
You are an API platform analyst reviewing a schema change for consumer impact.

Your task is to produce a consumer-facing impact summary from the provided API schema diff. Focus on what client developers need to know, not internal implementation details.

## INPUT

Schema Diff:
[SCHEMA_DIFF]

Current API Version: [CURRENT_VERSION]
Proposed API Version: [PROPOSED_VERSION]

Consumer Registry (known clients and their usage patterns):
[CONSUMER_REGISTRY]

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "summary": "One-paragraph executive summary of the change and its consumer impact",
  "breaking_changes": [
    {
      "change_description": "What changed",
      "affected_endpoints": ["list of endpoint paths"],
      "affected_consumers": ["list of known client IDs or names"],
      "breakage_mechanism": "How existing client code will fail (e.g., deserialization error, 400 on missing field, silent data loss)",
      "severity": "critical | high | medium | low",
      "migration_required": true,
      "estimated_migration_effort": "small | medium | large | breaking-rewrite",
      "migration_guidance": "Specific steps a consumer must take to adapt"
    }
  ],
  "non_breaking_changes": [
    {
      "change_description": "What changed",
      "affected_endpoints": ["list of endpoint paths"],
      "consumer_benefit": "What value this provides to consumers",
      "recommended_adoption": "Whether consumers should adopt immediately, eventually, or can ignore"
    }
  ],
  "deprecations": [
    {
      "deprecated_item": "Field, endpoint, or behavior being deprecated",
      "sunset_date": "Planned removal date or version",
      "replacement": "What consumers should use instead",
      "affected_consumers": ["list of known client IDs"]
    }
  ],
  "consumer_action_items": [
    {
      "consumer_id": "Client identifier",
      "required_actions": ["List of specific actions this consumer must take"],
      "deadline": "When action is needed by",
      "risk_if_no_action": "What happens if they don't migrate"
    }
  ],
  "rollback_considerations": "Whether this change can be safely rolled back after deployment and what consumers would experience during rollback"
}

## CONSTRAINTS

- Only report changes that affect consumers. Ignore internal-only changes like server-side middleware, logging, or implementation details.
- If a consumer is not in the registry, note it as "unknown consumers may be affected" in the summary.
- For each breaking change, explain the exact failure mode a consumer will experience—not just that it breaks.
- Severity must reflect consumer impact, not implementation difficulty.
- If no breaking changes exist, the breaking_changes array must be empty, not omitted.
- Do not invent consumer names or usage patterns. Use only what is provided in the consumer registry.
- If the consumer registry is empty or unavailable, state that impact assessment is limited and recommend consumer discovery before proceeding.

## RISK LEVEL

[RISK_LEVEL]

If RISK_LEVEL is "high", add a "human_review_required" boolean field to each breaking change and set it to true for any change affecting production consumers. Include a "reviewer_notes" field for a human to fill in.

To adapt this template for your environment, replace each placeholder with real data at runtime. [SCHEMA_DIFF] should contain the structured diff output from your schema comparison tool—ideally in a format the model can parse reliably, such as a JSON patch or a line-by-line textual diff with clear markers. [CONSUMER_REGISTRY] works best when populated from your API gateway logs, client SDK telemetry, or a manually maintained registry of known integrators. If you don't have a consumer registry, replace it with a note instructing the model to flag the gap rather than hallucinate clients. [RISK_LEVEL] should be set by your deployment pipeline based on the target environment: "low" for internal dev/staging changes, "high" for production-facing API modifications. After the model returns its output, validate the JSON structure against the schema before surfacing it to human reviewers or publishing it to consumers. A structural validation step catches missing arrays, null fields, and malformed severity values before they reach downstream systems.

This prompt is designed to be integrated into an automated API governance pipeline, not just used as a one-off manual analysis. The primary integration point is a CI/CD check that runs when an OpenAPI or GraphQL specification diff is detected in a pull request. The harness should extract the spec diff, assemble the required inputs—including the full previous spec, the proposed new spec, and a registry of known consumers—and pass them into the prompt. The output must be parsed as structured JSON and fed into downstream systems: a developer review queue for high-severity breaking changes, a changelog generator for consumer-facing communications, and a migration ticket creator for affected internal teams.

The implementation should enforce strict validation on both the input and output sides. Before calling the model, validate that the spec diff is parseable and that the consumer registry contains at least endpoint-to-client mappings. After receiving the model response, run a schema validator against the expected output shape—an array of consumer impact objects, each with fields for consumer_name, affected_endpoints, breaking_changes (boolean), migration_required (boolean), estimated_effort (enum of LOW/MEDIUM/HIGH), and recommended_action. If the output fails validation, retry once with a repair prompt that includes the validation error. If the retry also fails, escalate to a human reviewer and log the failure for prompt improvement. For high-risk API surfaces—those handling payments, authentication, or personally identifiable information—always require a human approval step before the analysis is published to consumers, regardless of model confidence.

Model choice matters for this workflow. Use a model with strong structured output capabilities and a large context window, as the combined previous spec, new spec, and consumer registry can easily exceed 8K tokens. If the total input exceeds the model's context limit, implement a pre-processing step that extracts only the changed paths and their dependent schemas, rather than passing the full specification. For teams using retrieval-augmented generation, store consumer integration patterns and historical migration notes in a vector database and retrieve the top-k relevant entries as additional context. Log every analysis run with the input diff hash, model version, output, validation result, and human review decision. This audit trail is essential for debugging false positives, tracking prompt drift, and demonstrating governance compliance to auditors.