Kur duhet të përdorni `async def` kundrejt `def` për endpoints?

Question

Accepted Answer

FastAPI suporton si `async def` ashtu edhe `def` të rregullt për operacionet e rrugës. Zgjedhja ka rëndësi për performancën: përdorni **`async def`** kur mundni të `await` I/O jo-bllokues, dhe **`def`** të rregullt kur kodi juaj thërret operacione bllokuese (sinkrone).

## Dy formate

```python
@app.get("/async")
async def async_endpoint():
    data = await fetch_from_api()        # await non-blocking I/O — efficient
    return data

@app.get("/sync")
def sync_endpoint():
    data = blocking_db_call()             # ordinary blocking code
    return data
```

## Si FastAPI trajton secilin

```text
async def → runs on the main event loop. Efficient ONLY if you await non-blocking calls.
            ⚠️ A BLOCKING call inside async def blocks the WHOLE event loop → kills concurrency!
def       → FastAPI runs it in a THREAD POOL, so blocking code doesn't block the event loop.
            Safe for synchronous/blocking libraries.
```

## Rregulli i vendimit

```python
# ✅ async def — when you can await async libraries (httpx, async DB drivers)
async def get_user():
    async with httpx.AsyncClient() as c:
        return await c.get(url)

# ✅ plain def — when using SYNCHRONOUS/blocking libraries (requests, sync ORM)
def get_user():
    return requests.get(url).json()       # blocking → FastAPI runs it in a thread

# ❌ THE DANGEROUS MISTAKE — blocking call inside async def
async def bad():
    return requests.get(url).json()       # blocks the event loop! Use `def` or an async client
```

Rregulli kritik: **asnjëherë mos vendosni thirrje bllokuese në `async def`** — kjo bllokoi event loop-in dhe shkatërron njëkohësinë. Ose përdorni një bibliotekë async me `await`, ose përdorni një `def` të thjeshtë (të cilin FastAPI e ekzekuton në mënyrë të sigurte në një thread pool).

## Pse ka rëndësi

Zgjedhja e saktë midis `async def` dhe `def` ndikon drejtpërdrejt në performancën dhe njëkohësinë e API-t tuaj, dhe gabimi është një lloj i zakonshëm, serioz.

Çështja kryesore është se **`async def` është e dobishme vetëm kur `await` operacione jo-bllokuese** — vendosja e një thirrjeje bllokuese (si biblioteka sinkrone `requests` ose një driver baze të dhënash bllokues) brenda `async def` bllokoi event loop-in e tërë, ngrin të gjitha kërkesa konkurente dhe e shkatërron qëllimin e async.

Nga ana tjetër, FastAPI në mënyrë të mençur ekzekuton endpoints `def` të thjeshtë në një thread pool, kështu që kodi sinkron/bllokues është i sigurt atje.

Kuptimi i këtij rregulli — përdorni `async def` me biblioteka vërtet async, përdorni `def` të thjeshtë për kodin bllokues, dhe asnjëherë mos përzieni thirrje bllokuese në `async def` — është thelbësor për shkrimin e endpoints FastAPI me përfomancë të mirë dhe shmangia e gabimit delikat por shkatërrues të serializimit aksidental të të gjitha kërkesave pas një event loop-i të bllokuar.