Multiple Values for the Same Query Parameter
When a query parameter needs to accept multiple values, there are several standard approaches. Choose one and document it clearly in your API.
Method 1: Repeated Parameters
?category=electronics&category=books&category=clothing
Pros: Simple, widely supported
Cons: Verbose for many values
Method 2: Comma-Separated Values
?category=electronics,books,clothing
?ids=1,2,3,4,5
Pros: Concise
Cons: Issues with values containing commas
Method 3: Array Notation
?category[]=electronics&category[]=books&category[]=clothing
?tags[0]=urgent&tags[1]=important
Pros: Clear array structure
Cons: Not universally supported
Method 4: Pipe-Separated
?category=electronics|books|clothing
Pros: Handles commas in values
Cons: Less common, potential encoding issues
Approach 1: Comma-Separated Values (CSV)
Format: ?param=value1,value2,value3
Best for: Simple lists (e.g., tags, IDs).
Basic Query Parameter Syntax
https://api.example.com/users?name=john&age=25&active=true
- Start with
?after the endpoint - Separate parameters with
& - Format:
key=value - URL encode special characters
Common Query Parameters
| Parameter | Purpose | Example |
|---|---|---|
limit | Pagination size | ?limit=10 |
offset / page | Pagination position | ?page=2&limit=10 |
sort | Sorting | ?sort=name |
filter / q | Search/filtering | ?q=john&status=active |
fields | Field selection | ?fields=id,name,email |