API Pagination Filtering and Sorting Design Guide
Design consistent REST API pagination, filtering, sorting, and response metadata patterns for scalable developer-friendly endpoints.
Prompt Template
You are a senior API platform architect. Design pagination, filtering, and sorting conventions for: API type: [public REST API, internal API, partner API, mobile backend] Resources/endpoints: [orders, users, events, invoices, products, etc.] Expected data volume: [rows per resource, growth rate, high-cardinality fields] Client needs: [admin UI, mobile app, BI export, partner sync, search results] Database/search backend: [Postgres, MySQL, Elasticsearch, DynamoDB, mixed] Consistency requirements: [real-time, eventually consistent, snapshot export, audit trail] Sorting needs: [created date, updated date, status, amount, name, custom relevance] Filtering needs: [status, date range, owner, tenant, tags, full text, numeric ranges] Backward compatibility constraints: [existing params, SDKs, versioning policy] Security and tenancy constraints: [RBAC, tenant isolation, field-level access] Performance constraints: [latency target, max page size, rate limits] Create: 1. Recommended pagination strategy with tradeoffs between cursor, offset, and keyset pagination 2. Standard query parameter naming rules for limit, cursor, sort, filters, and fields 3. Response envelope with pagination metadata and next/previous links 4. Filtering syntax examples for equality, ranges, arrays, dates, and text search 5. Sorting rules, stable tie-breakers, and invalid sort handling 6. Edge cases for deleted records, duplicate timestamps, permission changes, and empty pages 7. Error response examples for invalid filters, page size, cursor, and sort fields 8. OpenAPI documentation snippets and SDK guidance 9. Test plan covering performance, consistency, and compatibility 10. Migration plan if existing endpoints already use inconsistent patterns Make the design practical for production APIs and easy for external developers to understand.
Example Output
# API List Pattern: Orders Endpoint
Recommendation
Use cursor pagination for `/orders` because the table is high-volume, frequently updated, and partner sync jobs need stable traversal. Keep offset pagination only for small admin-only reference tables.
Request
GET /v1/orders?limit=50&after=ord_01J8...&status=paid&created_at_gte=2026-01-01&sort=-created_at
Response Envelope
{
"data": [{ "id": "ord_123", "status": "paid", "created_at": "2026-05-18T10:30:00Z" }],
"page": {
"limit": 50,
"has_more": true,
"next_cursor": "ord_01J8NEXT",
"sort": "-created_at,id"
}
}
Rules
- Default limit: 50; maximum: 200.
- Sorts must include a stable tie-breaker, usually `id`.
- Date filters use ISO 8601 and explicit suffixes: `created_at_gte` and `created_at_lt`.
- Invalid sort fields return `400 invalid_sort_field` with allowed values.
Edge Case
If an order becomes hidden because of permission changes between pages, skip it and continue. Do not return duplicate records to fill the page.
Tips for Best Results
- 💡Pick one pagination style per resource family and document the exceptions clearly.
- 💡Always define stable sort tie-breakers before shipping cursor pagination.
- 💡Test list endpoints with records inserted, updated, deleted, and permission-filtered during traversal.
Frequently Asked Questions
What is the API Pagination Filtering and Sorting Design Guide prompt?
Design consistent REST API pagination, filtering, sorting, and response metadata patterns for scalable developer-friendly endpoints. It's a free ChatGPT prompt template from our Coding collection — copy it, fill in the bracketed variables, and paste it into your AI tool.
Which AI tools work with this prompt?
It's written and tested for ChatGPT, Claude and Gemini. Any AI assistant that accepts free-form text prompts will handle it well.
How do I customize this ChatGPT prompt?
Replace the bracketed variables — such as [existing params, SDKs, versioning policy] — with your own details before running it. Pick one pagination style per resource family and document the exceptions clearly.
Is this prompt free to use?
Yes. Every prompt on PromptAtlas is free to copy, customize, and use — no signup required.
Related Prompts
Python FileNotFoundError Debugging Prompt
Debug Python FileNotFoundError from the exact traceback, resolved path, working directory, filesystem context, deployment environment, and failing operation.
Python ZeroDivisionError Debugging Prompt
Debug Python ZeroDivisionError from the exact traceback, operand values and types, data path, numeric semantics, runtime context, and failing input.
Python IndentationError Debugging Prompt
Debug Python IndentationError from the exact parser message, whitespace, block structure, source bytes, formatter settings, and runtime version.
Python SyntaxError: Invalid Syntax Debugging Prompt
Debug Python SyntaxError invalid syntax from the exact parser location, surrounding tokens, Python version, generated code, execution context, and minimal reproduction.
Python AttributeError: Object Has No Attribute Debugging Prompt
Debug Python AttributeError from the exact traceback, runtime object type, attribute contract, construction path, version, imports, and minimal reproduction.
Python UnboundLocalError Debugging Prompt
Debug Python UnboundLocalError from the exact traceback, binding scope, assignments, branches, closures, imports, runtime path, and minimal reproduction.