Modern examples of diverse REST API query parameter patterns

Quick tour of real REST API query parameter examples

Instead of starting with definitions, let’s jump straight into a few realistic URLs that show examples of diverse REST API query parameter examples you’ll encounter in modern systems:

GET /v1/users?status=active&role=admin
GET /v1/products?category=books&price_min=10&price_max=50&sort=-rating
GET /v1/articles?q=climate+change&limit=20&offset=40
GET /v1/orders?created_after=2024-01-01&created_before=2024-12-31
GET /v1/devices?fields=id,name,status&include=owner,location
GET /v1/events?cursor=eyJwYWdlIjoxfQ==&limit=50
GET /v1/metrics?group_by=country,device_type&aggregate=sum:views,avg:duration

These aren’t theoretical. Variations of these patterns show up in APIs from companies like Stripe, GitHub, and Google. The rest of this article breaks these into patterns and walks through examples of how to design and document them.

Simple filter query parameter examples

The starting point for most developers is the simple filter. This is the most common example of a REST API query parameter in the wild:

GET /v1/users?status=active&role=admin

You’re doing three things here:

• Selecting a resource collection (/v1/users)
• Narrowing it with filters (status, role)
• Leaving everything else (fields, sort order, pagination) at defaults

Other examples include:

GET /v1/tickets?priority=high
GET /v1/tickets?priority=high&assigned_to=123
GET /v1/cars?make=toyota&year=2020

Design tips based on these examples of diverse REST API query parameter examples:

• Prefer clear, flat names like status=active over encoded logic like filter=active_admins.
• Use consistent naming across resources (status, created_before, created_after).
• Decide early whether you allow multiple values, e.g. status=open,closed or repeated params like status=open&status=closed.

The CDC’s open data APIs, for example, use straightforward filters like state=CA and year=2023 in their Socrata-based endpoints, which makes experimentation in a browser or tools like curl very approachable.

Range and date filters: practical examples you’ll actually use

Modern APIs almost always need range filters, especially around time and numeric data. Here are some very common examples of date and numeric range parameters:

GET /v1/orders?created_after=2024-01-01&created_before=2024-06-30
GET /v1/measurements?temperature_min=70&temperature_max=100
GET /v1/transactions?amount_gte=1000&amount_lte=5000

Patterns you’ll see in real examples:

• _min / _max suffixes, e.g. price_min, price_max
• Comparison-style suffixes like _gte / _lte (greater-than-or-equal, less-than-or-equal)

If you’re exposing scientific or public health data, date filters become even more important. Many U.S. government APIs, including those surfaced via data.gov (https://www.data.gov/), rely on start_date and end_date parameters to slice large datasets without overloading clients or servers.

When you design your own examples of diverse REST API query parameter examples for ranges, aim for:

• ISO 8601 dates (2025-01-15) for clarity and interoperability.
• Clear suffix conventions (_before, _after or _gte, _lte) used consistently.

Search query examples: free text and structured filters

Search is where query strings start to get interesting. A simple example of a search parameter is the classic q:

GET /v1/articles?q=climate+change

This mirrors patterns used by Google and other search engines. But modern APIs often mix free-text search with structured filters. For instance:

GET /v1/articles?q=climate+change&author_id=42&published_after=2024-01-01

Other realistic examples include:

GET /v1/doctors?q=pediatrician&city=Boston&radius_miles=10
GET /v1/recipes?q=low+carb&max_calories=600&diet=vegetarian

Health-related platforms that surface information from sources like MedlinePlus (via NIH: https://medlineplus.gov/webservices.html) often use this pattern: a q parameter for the search term plus additional filters for language, topic, or audience.

When you design these examples of diverse REST API query parameter examples for search:

• Keep q as a short, conventional name for the main query.
• Add other filters as separate parameters rather than encoding everything into q.
• Document how search interacts with filters (e.g., does q search within the filtered subset?).

Pagination: offset, limit, and cursor examples

Pagination patterns are some of the best examples of how query parameters affect usability and performance.

Offset–limit pagination examples

Offset-based pagination is the classic example of a simple, readable approach:

GET /v1/articles?limit=20&offset=40

Here, limit controls page size and offset controls the starting index. Other examples include:

GET /v1/users?limit=50
GET /v1/orders?limit=100&offset=300

Offset pagination is easy to reason about, but it can get slow or inconsistent on very large datasets.

Cursor-based pagination examples

For APIs that expect heavy traffic or rapidly changing data, cursor-based pagination is increasingly common in 2024–2025. A cursor is an opaque token you pass back to the server:

GET /v1/events?cursor=eyJpZCI6IjEyMyJ9&limit=50

A follow-up page might look like:

GET /v1/events?cursor=eyJpZCI6IjQ1NiJ9&limit=50

GitHub’s REST API and many analytics APIs use cursor-style patterns. These are strong examples of diverse REST API query parameter examples that balance performance and a clean consumer experience.

Design guidance:

• Always return the next cursor in the response body or headers.
• Treat the cursor as opaque; clients should not try to parse it.
• Keep limit as a separate parameter so clients can tune page size.

Sorting and ordering: real-world examples

Sorting is another area where small query parameter decisions have long-term impact. A very common pattern is a sort parameter with field names:

GET /v1/products?sort=price

To support descending order, many APIs use a minus sign:

GET /v1/products?sort=-price

This style shows up in APIs that follow the JSON:API recommendation for sorting.

More expressive examples of sorting include:

GET /v1/products?sort=-rating,price
GET /v1/users?sort=last_name,first_name

Here, you sort first by rating (descending), then by price (ascending) as a tiebreaker. These patterns are some of the best examples of diverse REST API query parameter examples because they pack a lot of power into a small, readable string.

Tips:

• Use a consistent delimiter (commas are typical) for multiple sort fields.
• Document which fields are sortable to avoid confusion.
• Define a default sort order so clients get predictable behavior even without sort.

Sparse fieldsets and includes: optimizing payloads

Front-end teams care a lot about over-fetching. Query parameters can help control which fields and related resources get returned.

Field selection examples

A classic JSON:API-inspired example of field selection is:

GET /v1/users?fields=id,name,email

This tells the server to return only those fields for each user. Other examples include:

GET /v1/articles?fields=id,title,summary
GET /v1/products?fields=id,name,price,in_stock

If you’re building data-heavy views, these are some of the best examples of diverse REST API query parameter examples for improving perceived performance without touching infrastructure.

Relationship inclusion examples

To reduce the number of round trips, many APIs support an include parameter:

GET /v1/orders?include=customer,items

Or more nested variants:

GET /v1/orders?include=customer,items.product

This pattern is widely used in APIs that mirror relational data models. It’s worth studying examples from JSON:API (https://jsonapi.org/format/) if you’re designing a new system.

Design notes:

• Keep fields and include separate; they solve different problems.
• Be explicit about performance impacts in your docs when many includes are requested.

Aggregation and analytics: advanced query parameter examples

Analytics endpoints showcase some of the most interesting examples of diverse REST API query parameter examples because they combine grouping, filtering, and aggregation in compact query strings.

Consider an analytics endpoint for video views:

GET /v1/metrics/views?group_by=country,device_type&aggregate=sum:views,avg:watch_time

Here you have:

• group_by listing dimensions to group on.
• aggregate describing metrics and functions.

Other realistic examples include:

GET /v1/metrics/sessions?group_by=date&aggregate=count:sessions
GET /v1/metrics/traffic?group_by=source,medium&aggregate=sum:clicks,sum:impressions

These patterns are increasingly common in 2024–2025 as teams centralize analytics behind internal APIs rather than embedding SQL into every service.

If you work in healthcare or research, you’ll see similar ideas in APIs that expose aggregated statistics from public datasets, like those cataloged at healthdata.gov (https://healthdata.gov/). Query parameters often control grouping by region, age group, or time period.

Guidelines:

• Favor readable group_by and aggregate names over overloading a single query parameter.
• Document allowed aggregations clearly; don’t silently ignore invalid ones.

Versioning, localization, and feature flags in query strings

While headers are often preferred, query parameters still show up in versioning and localization examples of diverse REST API query parameter examples.

Versioning examples

You might see:

GET /users?v=2

or a more explicit example of versioning:

GET /users?api_version=2025-01-01

Stripe uses date-based API versions, though it typically passes them via headers. If you’re forced to use query parameters, keep the pattern consistent and easy to compare.

Localization examples

Localization examples include language and region parameters:

GET /v1/articles?lang=en-US
GET /v1/articles?lang=es-ES

Health information sites that aggregate content from sources like Mayo Clinic (https://www.mayoclinic.org/) or MedlinePlus frequently expose language parameters or path segments for locale. If you put locale in the query string, document fallback behavior when translations are missing.

Feature flag examples

For internal and testing scenarios, query parameters are often used as temporary feature toggles:

GET /v1/search?q=insomnia&experimental_ranker=v3

This is a pragmatic example of how query parameters can support A/B testing or gradual rollouts without changing the URL structure.

Putting it together: designing your own examples of diverse REST API query parameter examples

Looking across these patterns, a few design themes show up repeatedly in the best examples of diverse REST API query parameter examples:

• Consistency beats cleverness. Pick naming patterns (_min/_max, _before/_after, sort=-field) and apply them across your entire API.
• One concern per parameter. Use separate parameters for search (q), filters (status), pagination (limit, cursor), and sorting (sort) instead of overloading a single filter blob.
• Predictable defaults. Document what happens when parameters are omitted, and show concrete examples in your docs.
• Realistic sample URLs. Don’t just show GET /items. Show full URLs that mirror the real examples in this article so developers can copy, paste, and tweak.

If you’re updating an existing API in 2024–2025, you don’t need to adopt every pattern overnight. Start by standardizing naming, adding clearer docs, and sprinkling in better examples of diverse REST API query parameter examples. Over time, you can introduce more advanced patterns like cursor-based pagination and field selection where they deliver the most value.

FAQ: common questions about REST API query parameter examples

What are some practical examples of REST API query parameters for filtering?

Practical examples of filtering include URLs like:

GET /v1/users?status=active&role=admin
GET /v1/orders?created_after=2024-01-01&created_before=2024-06-30

These show typical patterns for categorical filters (status, role) and date ranges.

Can you give an example of pagination with both filtering and sorting?

A realistic example of combining these is:

GET /v1/products?category=electronics&price_min=100&price_max=1000&sort=-rating&limit=20&offset=40

This filters by category and price, sorts by rating descending, and returns the third page of results.

What are the best examples of query parameters for searching text content?

Some of the best examples include using q for the main search term plus additional filters:

GET /v1/articles?q=heart+disease&lang=en-US&published_after=2023-01-01

This mirrors patterns used in many public APIs and keeps the search term separate from structured filters.

How should I document examples of diverse REST API query parameter examples?

In your docs, show full URLs with realistic values, not just parameter tables. For each endpoint, include:

• A basic filter-only example
• A paginated and sorted example
• At least one advanced example of combined filters, search, and pagination

Linking to trusted references like JSON:API (https://jsonapi.org/format/) or government open data portals (such as https://data.gov/) can also help readers see how your patterns compare to widely used standards.

Is it okay to mix headers and query parameters for things like versioning and localization?

Yes, but be consistent. Many teams keep security and authentication in headers, while using query parameters for filters, pagination, and examples of diverse REST API query parameter examples like lang=en-US or v=2. If you support both headers and query parameters for the same concern, clearly document the precedence rules so clients know which one wins when both are present.