Pagination Contract Drift Detection Prompt

API pagination contracts are fragile. A cursor format change, a page size default shift, or a total count that stops being accurate will silently break every client that depends on predictable pagination behavior. This prompt detects drift between two API versions by comparing pagination metadata, cursor structures, link headers, and count semantics. Use it when you are reviewing an API spec diff, validating a new deployment against a published contract, or building a CI gate that rejects pagination contract violations before they reach production.

The prompt expects structured input describing the pagination contract for both versions—including cursor formats, page size defaults, total count availability, link header structures, and any version-specific pagination parameters. You must provide this as a side-by-side comparison object with fields for cursor_structure, page_size_behavior, count_semantics, link_header_format, and pagination_parameters. The output is a drift report with client-breaking change flags, severity ratings (BREAKING, COMPATIBLE, DEPRECATION), and migration notes. This is not a general API diff tool—it focuses exclusively on pagination behavior and will miss non-pagination breaking changes like field removals or type narrowing.

Do not use this prompt when you need a full API compatibility assessment, when pagination is handled entirely client-side with no server contract, or when you lack structured pagination metadata from both versions. The prompt cannot infer pagination behavior from raw HTTP response bodies alone—you must extract and structure the pagination contract first. For high-risk production gates, always pair the prompt output with automated contract tests that verify cursor stability, page size consistency, and count accuracy against live endpoints before allowing a deployment to proceed.

The following prompt template is designed to compare two API specifications or response samples and identify pagination contract drift. It focuses on cursor format changes, page size default shifts, total count accuracy, and link header consistency—the four most common sources of client-breaking pagination failures. Replace every square-bracket placeholder with real values before execution. The prompt expects structured input and produces a structured drift report that can be parsed by downstream automation.

textCopy
You are an API contract reviewer specializing in pagination behavior.

Compare the pagination contracts in [SPEC_OR_SAMPLE_A] (version [VERSION_A]) and [SPEC_OR_SAMPLE_B] (version [VERSION_B]).

Analyze these pagination dimensions:
1. Cursor format: encoding, structure, field names, and whether cursors are opaque or decodable.
2. Page size defaults: default limit, max limit, and whether the default changed.
3. Total count accuracy: presence of total, estimatedTotal, or count fields, and whether semantics shifted.
4. Link header consistency: rel values (next, prev, first, last), URI template changes, and header name changes.

[CONSTRAINTS]
- Flag a change as breaking if an existing client relying on [VERSION_A] behavior would fail without code changes.
- Treat additive fields as non-breaking unless they change required client parsing logic.
- If a field was optional and becomes required, flag as breaking.
- If a field was required and becomes optional, flag as additive with a deprecation note.

[OUTPUT_SCHEMA]
Return a JSON object with this exact structure:
{
  "drift_detected": boolean,
  "breaking_changes": [
    {
      "dimension": "cursor_format" | "page_size_defaults" | "total_count_accuracy" | "link_header_consistency",
      "severity": "breaking" | "warning" | "info",
      "field_path": string,
      "version_a_value": string,
      "version_b_value": string,
      "client_impact": string,
      "migration_note": string
    }
  ],
  "additive_changes": [ /* same structure as breaking_changes */ ],
  "compatible_changes": [ /* same structure as breaking_changes */ ],
  "summary": string,
  "recommended_action": "block_release" | "require_client_migration" | "safe_to_proceed" | "manual_review_needed"
}

[EXAMPLES]
Example breaking change:
Input A: {"cursor": "eyJpZCI6MTIzfQ=="} (base64-encoded JSON)
Input B: {"cursor": "123"} (raw integer)
Output: severity=breaking, client_impact="All clients decoding base64 cursors will fail to parse raw integer cursors."

Example non-breaking change:
Input A: {"pageSize": 20}
Input B: {"pageSize": 20, "maxPageSize": 100}
Output: severity=info, client_impact="New maxPageSize field is additive; existing clients ignoring it are unaffected."

[RISK_LEVEL]
This is a HIGH-RISK review. Pagination contract breaks cause silent data loss, infinite loops, and client crashes. Flag all cursor encoding changes as breaking unless proven compatible.

After pasting this template, replace [SPEC_OR_SAMPLE_A] and [SPEC_OR_SAMPLE_B] with either full OpenAPI/JSON Schema documents, representative response payloads, or pagination configuration objects. The [VERSION_A] and [VERSION_B] placeholders should contain version identifiers that appear in your drift report for traceability. The [OUTPUT_SCHEMA] block defines the exact JSON structure your harness should validate against after the model responds. If your API uses pagination mechanisms beyond the four listed dimensions—such as offset-based pagination, keyset pagination, or custom Link header variants—extend the dimension list in the prompt and add corresponding fields to the output schema. Always run the output through a JSON schema validator before ingesting it into your CI pipeline or deployment gate.

For production use, pair this prompt with a validation step that checks: (1) the output is valid JSON matching the schema, (2) every breaking_changes entry has a non-empty client_impact and migration_note, and (3) the recommended_action field is one of the four enumerated values. If validation fails, retry once with the validation error appended to the prompt as additional context. If the retry also fails, escalate for human review rather than silently accepting a malformed drift report. Do not use this prompt as the sole gate for production deployments—always combine it with contract tests that exercise actual client pagination loops against the new API version.

This prompt is designed to run as a scheduled or event-driven comparison step inside an API monitoring pipeline, not as a one-off chat interaction. The typical trigger is a new OpenAPI spec version, a detected change in a /.well-known endpoint, or a periodic crawl of live API responses. The harness should fetch the current contract (spec file or observed response schema) and the previous known-good contract, then pass both into the prompt as [CURRENT_CONTRACT] and [PREVIOUS_CONTRACT]. The prompt expects structured contract representations—ideally normalized JSON excerpts containing pagination-relevant fields: cursor formats, page size defaults, total count presence, link header structures, and next/prev token shapes. Do not pass raw HTTP response bodies without first extracting the pagination layer; the model needs the contract, not the payload.

Validation and retry logic is critical because this prompt outputs a structured drift report that downstream systems consume automatically. Implement a JSON schema validator on the output to confirm the presence of required fields: drift_detected (boolean), breaking_changes (array of objects with field, previous_value, current_value, client_impact), and recommendation (enum: no_action, notify_consumers, block_release). If validation fails, retry once with a repair prompt that includes the validation error and the raw output. If the retry also fails, escalate to a human reviewer via the on-call channel and log the failure for prompt improvement. For high-reliability pipelines, run the prompt against three model variants (e.g., GPT-4o, Claude 3.5 Sonnet, Gemini 1.5 Pro) and require at least two agreeing on breaking_changes before auto-blocking a release.

Model choice and latency budget depend on where this sits in your pipeline. For pre-merge CI checks where latency under 30 seconds is acceptable, use a frontier model with strong structured output support (GPT-4o with response_format or Claude with tool-use mode). For continuous monitoring of production endpoints where you're scanning dozens of APIs hourly, consider a smaller, fine-tuned model or a cached prompt prefix to reduce cost and latency. Always log the full prompt input, output, and validation result to your observability platform (Datadog, Grafana, or custom trace store) with the API version and timestamp as trace attributes. This makes drift decisions auditable and lets you replay historical comparisons when the prompt template changes.

Alert routing should map to the recommendation field. block_release findings must page the API platform on-call immediately and block the CD pipeline if integrated. notify_consumers findings should create a ticket in the developer relations queue with the full drift report attached. no_action findings can be logged silently. Before deploying this prompt to production, build a golden test set of at least 20 known contract pairs covering: cursor format changes (e.g., base64 to UUID), page size default shifts, total count removal, link header rel changes, and intentional non-breaking additions. Run these through the harness weekly as a regression gate. The most common failure mode is false positives on additive changes—tune the prompt's [CONSTRAINTS] block to explicitly distinguish additive from breaking pagination changes, and add counterexamples to your few-shot set for each false positive discovered in production.