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.
Related Prompts
Technical Documentation Writer
Generate clear, comprehensive technical documentation for APIs, functions, systems, or libraries.
Monorepo Build Cache Optimization Guide
Diagnose slow monorepo builds and create a practical optimization plan for local developer workflows, CI pipelines, caching, and dependency boundaries.
CLI Error Message and Exit Code UX Guide
Design developer-friendly command-line error messages with exit codes, stderr/stdout rules, recovery hints, logging behavior, docs, and regression tests.