Si punojnë parametrat e rrugës dhe parametrat e pyetjeve?

Question

Accepted Answer

FastAPI nxjerr **parametrat e rrugës** (pjesa e rrugës URL) dhe **parametrat e pyetjeve** (pas `?`) nga argumentet e funksionit, duke përdorur sugimet e tipeve për të konvertuar dhe validuar automatikisht.

## Parametrat e rrugës — pjesë e URL-it

```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)
```

Një parametër i funksionit emri i të cilit përputhet me `{placeholder}` në rrugë bëhet një **parametër i rrugës**. Sughimi i tipit (`int`) konverton automatikisht vargun nga URL-i dhe kthen një gabim të qartë 422 nëse nuk përputhet.

## Parametrat e pyetjeve — gjithçka tjetër

```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}
```

Parametrat e funksionit **jo** në rrugë bëhen **parametra të pyetjeve**. Një vlerë e parazgjedhur i bën ato opsionale (`skip: int = 0`); `str | None = None` bën një parametër opsional pyetjeje të pavlefshëm. Pa një vlerë të parazgjedhur, ato janë të detyruara.

## I detyrueshëm kundrejt opsionalit

```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
```

## Kombinimi i të dyjave

```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
```

## Pse është e rëndësishme

Parametrat e rrugës dhe pyetjeve janë mënyra se si pikat e fundore marrin hyrje nga URL-i — thelbësore për pothuajse çdo rrugë API (marrja e një zdreni sipas id-t, filtrimit, përcaktimit të faqes, kërkimit).

Qasja e FastAPI është elegante dhe një arsye kyçe që është produktive: thjesht deklarimi i parametrave të funksionit të tipizuar ju jep nxjerrje automatike, **konvertim të tipit**, **validim** (me gabime të qarta 422 në hyrje të keqe) dhe semantikën e detyrueshme-kundrejt-opsionale (përmes parazgjedhjes) — e gjithë e nxjerrë nga sugimet standarde të tipit Python, pa ndarje manuale.

Kuptimi i dallueshit (parametrat e rrugës vijnë nga `{placeholder}`, gjithçka tjetër është një parametër pyetjeje) dhe si parazgjedhjet kontrollojnë opsionalitetin është njohuri esenciale e përditshme për ndërtimin e pikave të fundore të FastAPI.