URL Anatomy — Paths, Query Parameters, and Fragments Explained

What You'll Learn

• The seven parts of a URL
• How APIs use the path to identify resources
• How APIs use query parameters to filter, sort, and paginate
• How to URL-encode special characters

Why This Matters

The URL is the address of an API resource. Get any part wrong — a missing slash, an unencoded space, a wrong port — and your request fails. Understanding URL anatomy is the difference between guessing at API errors and reading them precisely.

The Seven Parts of a URL

https://api.example.com:443/v1/users/123?active=true&sort=name#section
\___/   \______________/\__/\__________/\____________________/\______/
scheme       host       port    path          query string        fragment

The Path — Identifying Resources

In a REST API, the path identifies what you're interacting with. Each segment usually represents a resource or a resource collection:

/users                  → all users (collection)
/users/123              → user with ID 123 (single resource)
/users/123/posts        → all posts by user 123 (nested collection)
/users/123/posts/456    → post 456 by user 123

Path segments are separated by /. The last segment may be a collection (plural noun) or a specific resource ID.

Versioning in the path

Many APIs include a version prefix:

/v1/users/123
/v2/users/123

This lets the API introduce breaking changes in /v2/ without breaking existing /v1/ clients.

Query Parameters — Filtering, Sorting, Pagination

Query parameters appear after ? and are separated by &. They modify how the server returns the resource.

GET /users?role=admin&active=true&sort=name&page=2&limit=20

This request means: "give me page 2 of active admin users, sorted by name, 20 per page."

URL Encoding — Special Characters

Some characters have special meaning in URLs (?, &, =, #, /, spaces). If you need to include them in a value, you must URL-encode them:

Example — searching for "Anita & Ravi"

GET /search?q=Anita%20%26%20Ravi

Without encoding, the & would be parsed as a separator between two query parameters, breaking the search.

In code, use the language's URL encoder:

// JavaScript
encodeURIComponent("Anita & Ravi")    // "Anita%20%26%20Ravi"

# Python
from urllib.parse import quote
quote("Anita & Ravi")                # "Anita%20%26%20Ravi"

Common Mistakes

1. Forgetting to encode special characters. Spaces, ampersands, and equals signs in values break the URL.
2. Using uppercase in paths when the API expects lowercase. Paths are technically case-sensitive. /Users and /users are different URLs.
3. Putting authentication tokens in the URL. URLs are logged everywhere. Use the Authorization header instead.
4. Using query parameters for resource identification. /users?id=123 is wrong; /users/123 is right. Use the path for ID, query for filters.
5. Trailing slash inconsistency. /users and /users/ are different URLs. Pick one and stick with it.

Practical Exercise (5 minutes)

Break down this URL into its seven parts:

https://api.open-meteo.com/v1/forecast?latitude=19.07&longitude=72.87&current=temperature_2m

Answers:

• Scheme: https
• Host: api.open-meteo.com
• Port: (default 443, omitted)
• Path: /v1/forecast
• Query string: latitude=19.07&longitude=72.87&current=temperature_2m
• Fragment: none

Mini Challenge

Construct a URL that asks the JSONPlaceholder API for the first 5 posts by user ID 1, sorted by ID descending. (Hint: JSONPlaceholder supports ?userId=1 for filtering. It does not support pagination or sort parameters, so construct what you can and observe what the API ignores.)

Key Takeaways