Understanding URL Building in FastAPI

When we are familiar with the English language, we can often understand a concept by looking at how the word is used in everyday life.

In web development, we frequently hear terms such as URL, endpoint, request, response, path parameter, query parameter, and URL building.

Let's understand URL building step by step using a simple example.

What is a Request?

Imagine a classroom scenario.

Teacher: "Last week we discussed Back-End Engineering. Now we will discuss Cloud."

You were absent for the whole week, so you ask the teacher:

You: "I was absent for the whole week. Can you explain these topics to me?"

This is a normal daily-life request. You are asking the teacher for something.

The teacher may respond:

Teacher: "Okay, I'll explain it."

or:

Teacher: "Ask your friend; I don't have time right now."

This is the response to your request.

The same basic idea exists in web communication.

When a client makes a request to a server, the server processes the request and sends back a response.

Client
   |
   | Request
   ↓
Server
   |
   | Response
   ↓
Client

In Python, we can use libraries such as requests or httpx to make HTTP requests.

For example:

import requests

URL = "https://www.techsnap.in"

response = requests.get(URL)

Here, the Python program sends a GET request to the URL, and the server sends back a response.

Who Makes the Request?

The client makes the request.

A client can be:

• A web browser
• A mobile application
• A Python program
• Postman
• Another server

For example, when a user enters a URL into a browser, the browser acts as the client and sends an HTTP request to the server.

User
  ↓
Browser
  ↓
HTTP Request
  ↓
Server

What is an API Endpoint?

Before understanding URL building, we should understand an API endpoint.

An endpoint is a specific API location that a client can access to perform an operation.

For example, in FastAPI:

from fastapi import FastAPI

app = FastAPI()

@app.get("/products/{id}")
def get_product(id: int):
    return {"product_id": id}

Here:

GET /products/{id}

is the endpoint definition.

The server has defined this endpoint so that a client can request a particular product.

For example:

/products/2

The client can use this URL to request product 2.

What is URL Building?

Now we can understand URL building.

URL building is the process of constructing a complete URL that a client can use to make a request to an API endpoint.

It is important to understand that URL building does not mean creating the API endpoint.

The server defines the endpoint, while the client builds a URL to access that endpoint.

For example, the server defines:

@app.get("/products/{id}")
def get_product(id: int):
    ...

The endpoint pattern is:

/products/{id}

The client can build the actual URL:

http://127.0.0.1:8000/products/2

Here, the client has constructed a URL that points to the endpoint.

Breaking Down a URL

Consider this URL:

http://127.0.0.1:8000/products/2

It contains several parts:

http://       → Scheme
127.0.0.1     → Host
8000          → Port
/products/2   → Path

The complete URL tells the client where the server is located and which resource it wants to access.

URL Building with Path Parameters

Suppose our FastAPI application contains:

@app.get("/products/{id}")
def get_product(id: int):
    return {"product_id": id}

The {id} is a path parameter.

If the client wants product 2, it replaces {id} with 2:

/products/{id}
       ↓
/products/2

So the complete URL becomes:

http://127.0.0.1:8000/products/2

FastAPI receives the request and extracts:

id = 2

Then it passes that value to the endpoint function:

get_product(id=2)

URL Building with Query Parameters

A URL can also contain query parameters.

For example:

http://127.0.0.1:8000/products?category=phone

Here:

/products

is the path, while:

?category=phone

is the query parameter.

A query parameter follows the format:

key=value

Multiple query parameters can be added using &:

/products?category=phone&limit=10

Here:

category=phone
limit=10

are query parameters.

Query parameters are commonly used for:

• Filtering
• Searching
• Pagination
• Sorting
• Providing optional information

Path Parameter vs Query Parameter

Consider these two URLs:

Path Parameter

/products/2

Here, 2 is part of the path.

@app.get("/products/{id}")

It is commonly used to identify a specific resource.

Query Parameter

/products?id=2

Here, id=2 is a query parameter.

@app.get("/products")
def get_product(id: int):
    ...

The value is provided after ?.

So the difference is:

Path Parameter:
 /products/2

Query Parameter:
 /products?id=2

Both can provide the value 2, but they provide it in different parts of the URL.

Complete Request Flow

Now let's connect everything together.

Suppose the FastAPI application has:

@app.get("/products/{id}")
def get_product(id: int):
    return {"product_id": id}

The user wants product 2.

The client builds:

http://127.0.0.1:8000/products/2

The browser sends an HTTP request:

GET /products/2

The request reaches the server.

With FastAPI, the typical flow is:

Browser
   ↓
HTTP Request
   ↓
Uvicorn
   ↓
FastAPI
   ↓
Matching Endpoint
   ↓
get_product(id=2)
   ↓
HTTP Response
   ↓
Browser

Uvicorn acts as the ASGI server and communicates with the FastAPI application.

FastAPI matches the incoming request with the appropriate endpoint, extracts the required parameters, executes the endpoint function, and produces the response.

What Makes Up a URL?

A URL can contain several components:

https://example.com:8000/products/2?category=phone&limit=10

Conceptually:

https://
   ↓
Scheme

example.com
   ↓
Host

:8000
   ↓
Port

/products/2
   ↓
Path

?category=phone&limit=10
   ↓
Query Parameters

The client constructs the appropriate URL and uses it to make the HTTP request.

URL Building vs Endpoint Creation

This distinction is very important.

Endpoint Creation

The server/developer defines the endpoint:

@app.get("/products/{id}")
def get_product(id: int):
    ...

URL Building

The client constructs a URL to access that endpoint:

http://127.0.0.1:8000/products/2

Therefore:

Endpoint creation defines where and how the server accepts a request, while URL building constructs the URL that the client uses to reach that endpoint.

Final Mental Model

You can remember the entire concept like this:

Server
   |
   | Defines endpoint
   ↓
GET /products/{id}
   ↑
   |
   | Client builds URL
   |
http://127.0.0.1:8000/products/2
   |
   ↓
HTTP Request
   |
   ↓
Server
   |
   ↓
FastAPI processes request
   |
   ↓
HTTP Response
   |
   ↓
Client

URL building is the process of constructing a complete URL using components such as the scheme, host, port, path, path parameters, and query parameters so that a client can make an HTTP request to a particular API endpoint.