Pagination Contract Design Prompt

Use this prompt during the API design review phase, before a single line of implementation code is written. The ideal user is an API designer, backend engineer, or technical lead who has already defined the resource model and understands the collection's access patterns, typical data volumes, and expected consumer workflows. The prompt requires a concrete resource description and collection characteristics as input—it cannot design a pagination contract from a vague idea. The output is a complete, reviewable pagination contract that includes request parameters, response envelope structure, edge-case handling rules, and a documented rationale for the chosen strategy. This contract becomes the source of truth for implementation, client SDK generation, and API documentation.

Do not use this prompt when the resource model is still in flux, when you lack clarity on whether the collection is append-only or supports arbitrary insertion and deletion, or when the underlying data store imposes hard constraints that the API layer cannot abstract (for example, a legacy database that only supports offset-based queries with no cursor primitive). The prompt is also inappropriate for streaming or real-time data feeds where pagination is not the right access pattern—WebSockets, Server-Sent Events, or gRPC streaming require fundamentally different contracts. If you are retrofitting pagination onto an existing API with live consumers, use the Breaking Change Detection Prompt first to assess migration impact before designing the new contract.

Before running this prompt, gather the resource schema, expected collection size range, mutation patterns (append-only, mutable, or sorted), consumer latency requirements, and any consistency guarantees the system must provide. The prompt works best when you can describe the collection's behavior concretely: 'A time-ordered, append-only event log with millions of records per tenant, consumers polling for new events every 30 seconds' is actionable; 'a list of things' is not. After receiving the prompt output, review the recommended strategy against your operational constraints—cursor-based pagination requires a stable sort key, and page-based pagination can produce duplicate or missing results if the underlying data mutates between requests. If the prompt recommends a strategy your infrastructure cannot support, iterate with additional constraints rather than accepting the output as final. The next step is to validate the generated contract against the API Contract Consistency Review Prompt to catch parameter naming drift, envelope inconsistencies, and error format misalignment before the contract reaches implementation.

This prompt template is designed to produce a complete pagination contract recommendation for a specific API resource. It forces the model to reason about data volatility, client requirements, and operational constraints before selecting between offset, cursor, or page-based pagination. The output includes a full request/response contract, edge-case handling rules, and implementation guidance. Use this when you need a concrete, reviewable pagination design rather than a general discussion of pagination patterns.

codeCopy
You are an API design architect specializing in pagination contracts for REST and GraphQL APIs. Your task is to recommend and fully specify a pagination strategy for a specific resource collection.

## INPUT
- Resource Description: [RESOURCE_DESCRIPTION]
- Data Characteristics: [DATA_CHARACTERISTICS]
- Client Requirements: [CLIENT_REQUIREMENTS]
- Existing API Standards: [EXISTING_STANDARDS]
- Operational Constraints: [OPERATIONAL_CONSTRAINTS]

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "recommendation": {
    "strategy": "cursor" | "offset" | "page",
    "rationale": "string explaining why this strategy fits the resource and constraints",
    "trade_offs": ["list of trade-offs accepted with this choice"]
  },
  "request_contract": {
    "parameters": [
      {
        "name": "string",
        "type": "string",
        "required": boolean,
        "description": "string",
        "example": "string"
      }
    ],
    "default_page_size": number,
    "max_page_size": number
  },
  "response_envelope": {
    "data_field": "string",
    "pagination_metadata": {
      "fields": [
        {
          "name": "string",
          "type": "string",
          "description": "string"
        }
      ]
    },
    "example_response": {}
  },
  "edge_case_rules": [
    {
      "scenario": "string describing the edge case",
      "expected_behavior": "string describing the correct response",
      "status_code": number
    }
  ],
  "implementation_notes": ["list of implementation guidance for backend developers"],
  "client_usage_guidance": ["list of guidance for API consumers"]
}

## CONSTRAINTS
- Prefer cursor-based pagination when data is frequently inserted or deleted, or when real-time consistency matters.
- Use offset pagination only when data is relatively static and clients need random-access page jumping.
- Reserve page-based pagination for simple UIs with fixed page sizes and low data volatility.
- Every edge case rule must specify the exact HTTP status code and response body behavior.
- Include a Link header recommendation in implementation notes if using cursor or offset pagination.
- If the resource can return zero items, specify the empty collection response explicitly.
- Address what happens when a cursor becomes invalid between requests.

## RISK_LEVEL
[RISK_LEVEL]

If RISK_LEVEL is "high", flag any pagination design choices that could cause data loss, missed records, or infinite loops in consumers. Require explicit handling for concurrent modification scenarios.

To adapt this template, replace each square-bracket placeholder with concrete details about your resource. For [RESOURCE_DESCRIPTION], describe what the endpoint returns—such as "user-visible events ordered by creation time descending." For [DATA_CHARACTERISTICS], specify insertion patterns, deletion frequency, and whether ordering can change between requests. [CLIENT_REQUIREMENTS] should capture whether consumers need random access, infinite scroll, or export-all behavior. [EXISTING_STANDARDS] lets you reference your organization's API guidelines so the model aligns with internal conventions. Set [RISK_LEVEL] to "high" when pagination bugs could cause financial reconciliation errors, missed audit records, or data integrity issues—this triggers stricter edge-case analysis and explicit concurrency handling in the output.

After generating the contract, validate the output against your existing API style guide. Check that the recommended strategy doesn't conflict with your gateway's caching behavior or your monitoring system's assumptions about response structure. For high-risk resources, run the edge-case rules past a senior engineer before implementing—cursor invalidation and concurrent modification handling are the most common sources of pagination defects in production.

This prompt is designed to be called programmatically as part of an API design review pipeline, not as a one-off chat interaction. The harness should accept an OpenAPI fragment or a structured description of the resource collection as input, inject it into the [RESOURCE_SPEC] placeholder, and parse the model's JSON output for downstream consumption. Because pagination contract decisions affect every consumer of the API, the harness must treat the model's output as a draft recommendation, not a final decision. The output should be routed to a human reviewer or an architecture review board before the contract is published in the API specification.

Validation and retry logic is critical here. The harness must validate that the model's output contains all required fields: pagination_type, request_parameters (with at least page_size or limit), response_envelope (with items, next_cursor or equivalent), and edge_case_rules (covering empty results, first page, last page, and deleted items). If the output fails JSON schema validation, retry once with a repair prompt that includes the validation errors. If the retry also fails, log the failure and escalate to a human reviewer with the raw model output attached. Model choice matters: use a model with strong structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set response_format to json_object with the expected schema. Do not use smaller or faster models for this task—pagination contract errors are expensive to fix after implementation.

Logging and traceability should capture the input resource spec, the model's raw response, the validated output, and the reviewer's final decision. Store these artifacts alongside the API specification version so that future teams can understand why a particular pagination strategy was chosen. If the prompt is integrated into a CI/CD pipeline for API spec changes, gate the pipeline on human approval of the pagination contract before the spec change can merge. Avoid wiring this prompt directly into automated code generation without a review step—pagination design requires judgment about consumer use cases, data volatility, and infrastructure constraints that the model cannot fully assess from the spec alone.