Query Parameters and Path Parameters in Depth

Parameters are how you tell an API exactly what data you want. Path parameters identify specific resources, and query parameters filter, sort, and shape the results. This lesson covers every pattern you will encounter in production APIs.

---

1. Path Parameters: Identifying Resources

Path parameters are part of the URL structure. They identify a specific resource.

Single Resource

GET /users/42        # User with ID 42
GET /posts/7         # Post with ID 7
GET /orders/ORD-001  # Order with ID ORD-001

Nested Resources

GET /users/42/posts           # All posts by user 42
GET /users/42/posts/7         # Post 7 by user 42
GET /posts/7/comments         # All comments on post 7
GET /albums/3/photos          # All photos in album 3

Practice with JSONPlaceholder

# Get user 5
curl -s https://jsonplaceholder.typicode.com/users/5 | jq '.name'

# Get all posts by user 5
curl -s https://jsonplaceholder.typicode.com/users/5/posts | jq '.[].title'

# Get comments on post 3
curl -s https://jsonplaceholder.typicode.com/posts/3/comments | jq '.[].email'

---

2. Query Parameters: Filtering Collections

Query parameters appear after ? and modify which items are returned from a collection.

Basic Filtering

# Posts by user 1
curl -s "https://jsonplaceholder.typicode.com/posts?userId=1" | jq length

# Completed todos
curl -s "https://jsonplaceholder.typicode.com/todos?completed=true" | jq length

# Completed todos for user 3
curl -s "https://jsonplaceholder.typicode.com/todos?userId=3&completed=true" | jq length

Pagination

# Page 1, 10 items per page
curl "https://api.example.com/products?page=1&limit=10"

# Page 3, 25 items per page
curl "https://api.example.com/products?page=3&limit=25"

# Cursor-based pagination
curl "https://api.example.com/feed?after=cursor_abc123&limit=20"

Sorting

# Sort by price, ascending
curl "https://api.example.com/products?sort=price&order=asc"

# Sort by date, newest first
curl "https://api.example.com/products?sort=created_at&order=desc"

# Multiple sort fields
curl "https://api.example.com/products?sort=category,-price"
# The - prefix means descending

Searching

# Full-text search
curl "https://api.example.com/products?q=wireless+headphones"

# Search in specific field
curl "https://api.example.com/users?name=John"

Date Range Filtering

# Orders from January 2026
curl "https://api.example.com/orders?from=2026-01-01&to=2026-01-31"

# Events after a specific date
curl "https://api.example.com/events?after=2026-02-22T00:00:00Z"

Field Selection

# Only return name and email
curl "https://api.example.com/users?fields=name,email"

# Include related data
curl "https://api.example.com/posts?include=author,comments"

---

3. Combining Parameters

Real API calls often use multiple parameter types together:

# Get page 2 of user 1's completed todos, sorted by title
curl "https://api.example.com/todos?userId=1&completed=true&sort=title&page=2&limit=10"

URL breakdown:

https://api.example.com/todos
  ?userId=1            # Filter: only user 1
  &completed=true      # Filter: only completed
  &sort=title          # Sort: alphabetically by title
  &page=2              # Pagination: page 2
  &limit=10            # Pagination: 10 per page

---

4. Path vs Query: Decision Guide

graph TD
    A[What do you need?] --> B{Identify a specific resource?}
    B -->|Yes| C["Path parameter<br/>/users/42"]
    B -->|No| D{Filter a collection?}
    D -->|Yes| E["Query parameter<br/>/users?role=admin"]
    D -->|No| F{Sort results?}
    F -->|Yes| G["Query parameter<br/>/users?sort=name"]
    F -->|No| H{Paginate?}
    H -->|Yes| I["Query parameter<br/>/users?page=2"]
    H -->|No| J{Search?}
    J -->|Yes| K["Query parameter<br/>/users?q=john"]

    style C fill:#4f46e5,color:#fff
    style E fill:#059669,color:#fff
    style G fill:#059669,color:#fff
    style I fill:#059669,color:#fff
    style K fill:#059669,color:#fff

Use Case	Type	Example
Get user 42	Path	/users/42
Get active users	Query	/users?status=active
User 42's posts	Path	/users/42/posts
User 42's recent posts	Path + Query	/users/42/posts?sort=date&order=desc
Search users	Query	/users?q=john
Page 3 of users	Query	/users?page=3&limit=20

---

5. URL Encoding

Special characters in query values must be URL-encoded:

Character	Encoded	Example Use
Space	%20 or +	?q=hello+world
&	%26	?q=rock%26roll
=	%3D	?formula=1%2B1%3D2
+	%2B	?q=C%2B%2B
#	%23	?color=%23FF0000
@	%40	?email=user%40test.com

# cURL handles basic encoding
curl "https://api.example.com/search?q=hello%20world"

# Use --data-urlencode for automatic encoding
curl -G --data-urlencode "q=C++ programming" https://api.example.com/search

---

6. Common Parameter Anti-Patterns

Anti-Pattern	Problem	Better
?id=42 for a single resource	Unclear path	/resources/42
?action=delete	Action in parameter	DELETE /resources/42
?format=json	Format in parameter	Accept: application/json header
Deeply nested query params	Complex	Simplify or use POST body

---

Summary and Key Takeaways

1. Path parameters identify specific resources: /users/42.
2. Query parameters filter, sort, search, and paginate: ?status=active&sort=name.
3. Combine both: /users/42/posts?sort=date&page=2.
4. URL-encode special characters in query values.
5. Use path for identification, query for everything else.
6. Real API calls often combine 3-5 query parameters together.

---

Lesson Review Quiz