Bagaimana cara kerja parameter path dan parameter query?

Question

Accepted Answer

FastAPI mengekstrak **parameter path** (bagian dari path URL) dan **parameter query** (setelah `?`) dari argumen fungsi, menggunakan tipe hint untuk konversi dan validasi otomatis.

## Parameter path — bagian dari URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

Parameter fungsi yang namanya cocok dengan `{placeholder}` dalam path menjadi **parameter path**. Tipe hint (`int`) secara otomatis mengkonversi string dari URL dan mengembalikan error 422 yang jelas jika tidak cocok.

## Parameter query — semuanya yang lain

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Parameter fungsi yang **bukan** dalam path menjadi **parameter query**. Nilai default membuatnya opsional (`skip: int = 0`) ; `str | None = None` membuat parameter query opsional yang nullable. Tanpa nilai default, mereka diperlukan.

## Wajib vs opsional

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## Menggabungkan keduanya

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## Mengapa ini penting

Parameter path dan query adalah cara endpoint menerima input dari URL — fundamental untuk hampir setiap rute API (mengambil resource berdasarkan id, filtering, pagination, pencarian).

Pendekatan FastAPI elegan dan merupakan alasan kunci mengapa produktif: cukup deklarasikan parameter fungsi yang diketik memberikan ekstraksi otomatis, **konversi tipe**, **validasi** (dengan error 422 yang jelas pada input yang buruk), dan semantik wajib-vs-opsional (melalui default) — semuanya diturunkan dari tipe hint Python standar, tanpa parsing manual.

Memahami perbedaannya (parameter path berasal dari `{placeholder}`, semuanya yang lain adalah parameter query) dan bagaimana default mengontrol optionalitas adalah pengetahuan penting sehari-hari untuk membangun endpoint FastAPI.