How to Design URL for Filter Endpoint in REST API

Design filter endpoints by using query parameters in the URL to specify filter criteria, like /items?color=red&size=medium. This keeps URLs simple, readable, and flexible for multiple filters without changing the endpoint path.

Syntax

A filter endpoint URL typically uses query parameters after the base path. The syntax is:

• /resource?key1=value1&key2=value2
• resource is the main data collection.
• key=value pairs define filter conditions.
• Multiple filters are joined by &.

http

/items?color=red&size=medium&in_stock=true

Example

This example shows a REST API endpoint URL filtering products by color, size, and availability.

http

GET /products?color=blue&size=large&available=true HTTP/1.1
Host: api.example.com

Response:
[
  {"id": 101, "name": "Blue Jacket", "size": "large", "available": true},
  {"id": 102, "name": "Blue Jeans", "size": "large", "available": true}
]

Output

[{"id": 101, "name": "Blue Jacket", "size": "large", "available": true}, {"id": 102, "name": "Blue Jeans", "size": "large", "available": true}]

Common Pitfalls

Common mistakes when designing filter URLs include:

• Using path segments for filters, which makes URLs rigid and less flexible.
• Not encoding special characters in query values.
• Using inconsistent parameter names or formats.
• Ignoring case sensitivity or data types in filters.

Correct design uses query parameters consistently and encodes values properly.

http

Wrong:
GET /products/color/red/size/large

Right:
GET /products?color=red&size=large

Quick Reference

Concept	Description	Example
Base URL	Main resource path	/products
Query Parameter	Filter key-value pair	?color=red
Multiple Filters	Join with &	?color=red&size=medium
Boolean Filter	True/false values	?available=true
Encoding	Escape special chars	?name=red%20shirt

Key Takeaways

Use query parameters after the base URL to apply filters flexibly.

Keep filter keys consistent and encode special characters properly.

Avoid using path segments for filters to maintain URL simplicity.

Combine multiple filters with & to refine results easily.

Design URLs to be readable and intuitive for developers and users.