Query Parameters vs Path Parameters: The Address System

Alright, let's talk about something that confuses a lot of beginners. When you're designing an API, you need to send information to the server, right? There are two main ways to do this in the URL itself: path parameters and query parameters.

Let's look at a story that makes it crystal clear.

The Library Analogy

Imagine you walk into a huge library. You want to find a specific book. There are two ways to describe what you want:

Method 1: The Shelf Address (Path Parameters) "I want the book on Shelf 5, Row 3, Position 12"

• This is specific, structured, hierarchical
• You're navigating through a tree: Building → Floor → Shelf → Row → Position

Method 2: The Description (Query Parameters) "I want books about cooking, published after 2020, sorted by rating"

• These are filters and options
• You're describing characteristics you want

Path Parameters: The Hierarchical Structure

Think of path parameters as parts of the address itself. Let me show you:

Example 1: Getting a Specific User

━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Breaking it down:

"Get the specific user with ID 42"

Notice how 42 is part of the path. It's like saying "Go to apartment building USERS, unit number 42."

Here's another example:

Example 2: Getting a Specific Post by a Specific User ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Reading it hierarchically:

/users

"Start with users"

/42

"Find user with ID 42"/posts ← "Look at that user's posts"

/7

"Get post with ID 7"

It's like a filing system: Cabinet → Drawer → Folder → Document

Let’s see when to Use Path Parameters

Use path parameters when:

1. You're identifying a specific resource
2. The parameter is required
3. The parameter is part of a hierarchy

Real examples from famous APIs:

GitHub API:

Reading: "Get issue #123 from the react repo owned by facebook"

Twitter API (historical):

owner repo type issue

username type tweet ID

Reading:

"Get tweet #987654321 from user elonmusk"

Query Parameters: The Filters and Options

Now, query parameters are different. They're like adding filters to your search. They come after a ? in the URL.

Let me show you:

Example 1: Searching for Users ━━━━━━━━━━━━━━━━━━━━━━━━━━

GET /books/12345 ← WHICH book? #12345

GET /users/john/orders/99 ← WHICH user's WHICH order?

GET books?format=pdf&lang=spanish

← HOW do I want books? PDF, Spanish

GET /users?status=active&role=admin

← HOW do I want to filter users?

GET /reviews?movie_id=123&rating=5&sort=date

GET /movies/123/reviews?rating=5&sort=date

Path param Query params (WHICH movie) (HOW to filter/sort)

GET /posts/456

GET /authors/john/posts

Option B:

GET /posts?author=john

GET /posts?author=john&category=tech&status=published&limit=10

GET products?category=laptops&brand=dell&min_price=500&max_price=1500&ram=16GB&sort=price_low_to_high&page=2&limit=20

GET /api?resource=users&id=42

GET /users/42

Bad: GET /users/active/admin/seattle

Good:

GET /users?status=active&role=admin&city=seattle

Bad: GET/companies/123/departments/456/teams/789/employees/111/tasks/222

Good:

GET /tasks/222

Or:

GET /employees/111/tasks/222