Pagination, filtering, and search UX for APIs — Patterns & Anti‑Patterns — Practical Guide (Jan 23, 2026)
Level: Intermediate
Pagination, filtering, and search UX for APIs — Patterns & Anti‑Patterns
January 23, 2026
Prerequisites
This article assumes familiarity with RESTful API design principles, HTTP semantics, and basic query parameter handling. Understanding concepts like API versioning, resource-oriented design, and HTTP status codes will help you follow the recommendations and rationale. Practical experience with web or mobile client development or backend services that consume or provide APIs is also useful.
Many concepts here apply equally to REST and GraphQL APIs, but examples focus primarily on RESTful HTTP APIs as of 2026, with references to relevant features in commonly used frameworks (e.g. OpenAPI 3.x specifications, JSON:API 1.1).
Hands-on steps
1. Pagination — patterns that work
For most API endpoints returning collections, it is essential to limit payload size for performance and UX. The two common API pagination styles with strong tooling support today are offset-based and cursor-based pagination.
Offset-based pagination: Uses limit and offset query parameters. Simple but can cause performance issues and duplicate entries with concurrent updates to data.
GET /api/items?limit=20&offset=40
Cursor-based pagination: Uses opaque cursors returned from the server as tokens to retrieve the next page, e.g. a base64-encoded ID or timestamp. This approach is more performant and reliable for realtime/updating datasets but slightly more complex to implement.
GET /api/items?limit=20&cursor=eyJpZCI6ICI1NzYzNDUifQ==
When to choose: Use offset pagination for simple, static datasets or admin UIs with infrequent writes. Cursor pagination is preferred for large, dynamic datasets especially supporting feeds, scrolling, or realtime data.
2. Filtering — enabling expressive queries without complexity
Filtering lets clients narrow down resource collections. Good filter design balances expressivity with simplicity and security.
Recommended pattern: Use explicit, well-documented query parameters for each filter field, avoiding generic filter syntax that requires parsing arbitrary strings.
GET /api/users?role=admin&created_after=2025-01-01&is_active=true
This approach enhances discoverability, supports type validation, and enables API gateways and caching proxies to function effectively.
Advanced filtering: When clients require complex queries (e.g. logical operators AND/OR, nested conditions), consider adopting standards like JSON:API filtering conventions or the Open Data Protocol (OData). Alternatively, GraphQL’s query language naturally supports complex filters.
When to choose: Use explicit simple filters for public REST APIs and basic internal APIs. For complex querying needs or heavy integrations, consider JSON:API or GraphQL.
3. Search — full text and relevance ranking
Searchability requires more than simple substring matching. Implementing performant, user-friendly search often involves backend search engines (Elasticsearch, Solr) or database full-text indexes.
Pattern for RESTful API search: Use a dedicated query parameter such as q or search.
GET /api/documents?q=performance+optimisation
Optionally combine with pagination and filtering parameters. Avoid overloading filtering parameters for full-text search to keep syntax clear.
Relevance controls: Provide optional parameters to tune search behaviour, e.g. minimum score threshold, fields to search, or fuzzy matching controls—but document defaults clearly.
When to choose: For simple exact matches, use filtering. For anything needing tokenization, stemming, ranking, or typos, use a dedicated search parameter backed by a search engine integrated with the API.
Common pitfalls
- Mixing pagination styles: Don’t expose multiple competing pagination schemes on the same endpoint. Pick one primary pattern and stick to it for consistency.
- Using generic filter parameters without clear syntax: This leads to hard-to-parse, undocumented queries and brittle clients. Avoid passing semi-structured filter expressions without strong specification.
- Returning entire datasets: Omitting pagination causes overload on clients and servers. Always limit responses by default, e.g. default
limit=50. - Not supporting stable sort order with pagination: Always combine pagination with a deterministic and stable sorting order (e.g. by creation date plus unique ID) to avoid inconsistent page results.
- Lack of metadata: Not returning pagination metadata (total count, next/prev links) weakens usability and client navigation experience. Provide these in standardised response envelopes.
- Ignoring security and performance: Complex filters that translate to unindexed DB queries or unrestricted full-text queries can degrade production. Use parameter validation and query complexity limits.
Validation
Implementing robust server-side validation for pagination, filtering, and search parameters is critical to prevent abuse and improve API reliability.
- Pagination: Enforce maximum limits on
limitvalues suitable for your backend capacity (common maximums are between 50 and 1000). - Cursor tokens: Validate format and expiry of cursors to avoid injection or replay issues.
- Filters: Validate types (dates, enums, booleans) strictly to avoid injection and ensure meaningful errors.
- Search queries: Sanitize terms and limit length to prevent performance issues and injection attacks.
Use API schema validation tools (OpenAPI 3.x, JSON Schema) to automate much of this validation and provide client feedback and documentation generation.
Checklist / TL;DR
- Choose and consistently implement a single pagination strategy (offset or cursor) per endpoint.
- Use explicit, typed query parameters for filters; avoid opaque filter syntax unless following a known standard.
- Separate full-text search parameters from filters; back them with dedicated search infrastructure.
- Provide stable sorting alongside pagination to ensure reliable page results.
- Always limit page sizes and validate parameters rigorously.
- Include pagination metadata (next/prev links, counts) in API responses.
- Use API schema validation and document all query parameters clearly.
- Monitor performance impact of filtering/search and adjust limits accordingly.
- Consider JSON:API or GraphQL for complex querying and flexibility.