API Versioning Strategy Evaluation Prompt

This prompt is for architects and technical leads who have already decided that API versioning is necessary and must now choose the mechanism: URL path, custom header, media type (content negotiation), or query parameter. It is not a prompt for debating whether to version at all. The prompt forces a structured comparison across consumer ease, cache efficiency, tooling compatibility, and long-term evolvability, weighted against your specific team context, consumer profile, and operational constraints. Use it when a team is deadlocked on a versioning approach, when you need to document rationale for an ADR, or when a new API surface is being designed and the versioning strategy will be locked in for years.

The prompt expects you to provide concrete context about your API consumers (internal services, mobile apps, third-party developers, browser clients), your existing infrastructure (API gateway capabilities, CDN caching layers, observability tooling), and your operational constraints (release cadence, deprecation window, team size). Without this context, the prompt will produce a generic comparison that adds little value. The output is a weighted trade-off matrix with a recommended approach and explicit rationale, not a one-size-fits-all answer. The prompt is designed to surface hidden assumptions—for example, teams often default to URL versioning without considering that CDN cache fragmentation or OpenAPI tooling limitations might make header-based versioning a better fit for their specific consumer mix.

Do not use this prompt when the versioning decision is already made and you only need documentation, when you are evaluating a single mechanism in isolation without comparison, or when the API has no external consumers and versioning can be avoided entirely through backward-compatible evolution. Also avoid this prompt if you lack the consumer and infrastructure context to fill the required placeholders—the output quality degrades sharply when the model must invent assumptions about your operational reality. After running the prompt, validate the output against your actual API gateway capabilities and consumer contracts before committing the recommendation to an ADR. The prompt is a decision-support tool, not a replacement for reviewing the recommendation with the teams who will operate the chosen strategy.

This prompt template is designed to evaluate API versioning strategies—URL path, header-based, media type, and query parameter versioning—against your specific API context. It produces a structured trade-off analysis across consumer ease, cache efficiency, tooling compatibility, and evolvability, along with a weighted decision rubric. Replace each square-bracket placeholder with your team's actual constraints, consumer profiles, and architectural context before sending to the model. The prompt is self-contained and can be used without the rest of the playbook, though you should review the evaluation criteria and failure modes documented elsewhere in this guide before relying on the output for production decisions.

textCopy
You are an API architecture reviewer specializing in versioning strategy evaluation. Your task is to analyze the provided API context and produce a structured trade-off analysis comparing URL path, header-based, media type, and query parameter versioning approaches.

## INPUT

### API Context
[API_DESCRIPTION: Describe the API surface, primary consumers, current maturity, and any existing versioning approach.]

### Consumer Profiles
[CONSUMER_PROFILES: List consumer types with their technical capabilities, caching infrastructure, and tolerance for breaking changes. Include internal vs external, mobile vs server-side, and gateway/proxy usage.]

### Constraints
[CONSTRAINTS: Document non-negotiable requirements such as existing CDN behavior, API gateway limitations, client library support, regulatory requirements, or organizational standards.]

### Team Context
[TEAM_CONTEXT: Describe team size, API governance maturity, documentation practices, and capacity for maintaining multiple versions.]

### Risk Level
[RISK_LEVEL: Specify 'low', 'medium', or 'high' based on the blast radius of a versioning mistake. High-risk APIs require explicit human review gates.]

## OUTPUT SCHEMA

Return a JSON object with the following structure:

{
  "analysis": {
    "url_path_versioning": {
      "consumer_ease": "string (high/medium/low with explanation)",
      "cache_efficiency": "string (high/medium/low with explanation)",
      "tooling_compatibility": "string (high/medium/low with explanation)",
      "evolvability": "string (high/medium/low with explanation)",
      "risks": ["string array of specific risks"],
      "best_for": "string describing ideal use case"
    },
    "header_versioning": { "...same structure..." },
    "media_type_versioning": { "...same structure..." },
    "query_parameter_versioning": { "...same structure..." }
  },
  "decision_matrix": {
    "criteria": [
      {
        "criterion": "string",
        "weight": "number (1-10)",
        "scores": {
          "url_path": "number (1-10)",
          "header": "number (1-10)",
          "media_type": "number (1-10)",
          "query_param": "number (1-10)"
        }
      }
    ],
    "weighted_totals": {
      "url_path": "number",
      "header": "number",
      "media_type": "number",
      "query_param": "number"
    }
  },
  "recommendation": {
    "primary": "string (chosen strategy)",
    "rationale": "string (2-3 sentences explaining the choice)",
    "runner_up": "string (second-best option)",
    "migration_considerations": ["string array of practical concerns"],
    "open_questions": ["string array of questions the team should resolve before finalizing"]
  },
  "confidence": "string (high/medium/low with explanation of what would increase confidence)"
}

## CONSTRAINTS

- Score each strategy independently before comparing. Do not anchor on the first strategy evaluated.
- If [RISK_LEVEL] is 'high', include explicit human review gates in the recommendation.
- If consumer profiles include mobile clients, weight cache efficiency higher.
- If consumer profiles include third-party developers, weight consumer ease higher.
- If an API gateway or CDN is mentioned in constraints, explicitly address how each strategy interacts with it.
- Do not recommend a strategy that violates any documented constraint.
- Flag any missing information that would materially change the recommendation.
- If multiple strategies could work, explain the trade-off rather than forcing a false consensus.

To adapt this template, start by filling in the API context with enough detail that someone unfamiliar with your system could understand the surface area and consumer landscape. The consumer profiles section is critical—versioning strategy is fundamentally about consumer impact, so be specific about who consumes your API and how. For the constraints section, include infrastructure realities like CDN behavior with URL variants, API gateway capabilities, and any organizational standards that preempt certain choices. The risk level determines how conservative the recommendation should be; set it to 'high' for revenue-critical or safety-relevant APIs. After receiving the output, validate that the decision matrix weights align with your actual priorities—the model may weight criteria differently than your team would. Run the output through the evaluation checks documented in the testing section of this playbook before presenting the recommendation to stakeholders.

This prompt is designed to be integrated into an architecture review pipeline, not used as a one-off chat. The harness must enforce structured input, validate the model's output against a known schema, and provide a clear path for human review before the recommendation becomes a team decision. The core integration pattern is: collect structured context from the API designer, assemble the prompt, call the model, validate the output, and surface the trade-off analysis in a review tool or ADR template.

Input collection should be a form or CLI that gathers the required placeholders: [API_CONTEXT] (consumer types, scale, team maturity), [CURRENT_CONTRACT_SNIPPET] (the API surface under review), [CONSTRAINTS] (tooling, organizational policies, regulatory requirements), and [WEIGHTING_PREFERENCES] (ranked importance of consumer ease, cache efficiency, tooling compatibility, and evolvability). Do not let users paste free-text without structure—unstructured input produces inconsistent evaluations. Store these inputs as a versioned record so the evaluation can be reproduced later. Model choice matters: use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Smaller or faster models tend to skip trade-off dimensions or produce shallow comparisons. Set temperature to 0 or very low (0.0–0.2) to maximize consistency across runs. Output validation is critical. Define a JSON schema that the response must conform to, including required fields: recommended_strategy, trade_off_matrix (an array of objects with dimension, url_versioning_score, header_versioning_score, media_type_versioning_score, query_param_versioning_score, and rationale), decision_rubric (weighted scoring breakdown), risks, and mitigations. If the model output fails schema validation, retry once with the validation error injected into the prompt as feedback. If it fails twice, escalate for human review rather than silently accepting a malformed response.

Logging and audit are essential because versioning decisions have long-lived consequences. Log the full prompt, model response, validation result, and reviewer decision. Store these alongside the API specification version so future teams understand why a versioning strategy was chosen. Human review is mandatory before adoption—this prompt produces a recommendation, not a binding decision. The output should be rendered in a review UI that highlights the top recommendation, the trade-off matrix as a visual table, and the risks section. Allow reviewers to override the recommendation and capture their rationale. Retry logic should handle common failure modes: schema non-conformance (retry with schema feedback), refusal or safety block (escalate immediately), and truncated output (increase max_tokens and retry). Do not implement automatic retry loops beyond two attempts—brittle outputs indicate a deeper prompt or context problem that needs human diagnosis. Integration points include architecture review tools, API gateways with policy-as-code, and ADR generators. Wire the validated output into your ADR template by mapping recommended_strategy to the Decision section, trade_off_matrix to the Consequences section, and risks to the Risks section. This creates a traceable decision record without manual transcription.