Hoe ga je om met formuliergegevens en bestandsuploads?

Question

Accepted Answer

FastAPI verwerkt HTML **formuliergegevens** (`Form`) en **bestandsuploads** (`File`/`UploadFile`) — anders dan JSON-bodies, omdat ze verschillende content types gebruiken (`multipart/form-data`). Beide worden gedeclareerd met speciale parametertypen.

## Formuliervelden

```python
from fastapi import Form

@app.post("/login")
def login(username: str = Form(), password: str = Form()):   # form fields, not JSON
    # data comes as application/x-www-form-urlencoded or multipart/form-data
    return {"username": username}
```

Gebruik `Form()` om HTML-formuliervelden te ontvangen (bijv. een inlogformulier). Opmerking: een route kan gebruikmaken van **óf** een JSON-body **óf** formuliergegevens, niet beide tegelijk, omdat het verschillende content types zijn. (Vereist dat `python-multipart` is geïnstalleerd.)

## Bestandsuploads

```python
from fastapi import File, UploadFile

@app.post("/upload")
async def upload(file: UploadFile):                  # a single file
    contents = await file.read()                      # read the file's bytes
    file.filename                                      # original name
    file.content_type                                  # MIME type
    # save it:
    with open(f"uploads/{file.filename}", "wb") as f:
        f.write(contents)
    return {"filename": file.filename, "size": len(contents)}
```

`UploadFile` is het aanbevolen type — het is een spooled file (grote bestanden gaan naar schijf, niet allemaal in het geheugen), met async-methoden (`read`, `write`, `seek`) en metadata. Gebruik het in plaats van raw `bytes` voor alles behalve minuscule bestanden.

## Meerdere bestanden en formulier + bestand samen

```python
@app.post("/upload-many")
async def upload_many(files: list[UploadFile]):       # multiple files
    return [f.filename for f in files]

@app.post("/profile")
async def profile(name: str = Form(), avatar: UploadFile = File()):
    # combine form fields AND a file upload in one multipart request
    ...
```

## Uploads valideren (beveiliging!)

```python
if file.content_type not in ["image/jpeg", "image/png"]:   # check type
    raise HTTPException(400, "Invalid file type")
# also: limit file SIZE, sanitize filenames, scan content — uploads are untrusted input
```

## Waarom het belangrijk is

Het verwerken van formuliergegevens en bestandsuploads is een veel voorkomende, praktische behoefte — inlogformulieren, profielafbeeldinguploads, documentinzendingen en API's voor bestandsverwerking vereisen dit allemaal, en het werkt anders dan de JSON-bodies die FastAPI standaard gebruikt.

Het begrijpen van `Form()` voor formuliervelden en vooral **`UploadFile`** voor uploads (de aanbevolen aanpak, omdat het grote bestanden naar schijf spoolt in plaats van alles in het geheugen te laden — belangrijk voor het verwerken van grote bestanden zonder het RAM uit te putten) is noodzakelijk voor deze functies.

Evenals belangrijk is de **beveiligingsverantwoordelijkheid** die gepaard gaat met uploads: omdat geüploade bestanden onbetrouwde invoer zijn, het valideren van hun type en grootte, het saneren van bestandsnamen en voorzichtigheid hoe je ze opslaat/serveert is essentieel om kwetsbaarheden te voorkomen.

Weten hoe je formuliervelden ontvangt, enkele en meerdere bestandsuploads verwerkt, formulieren met bestanden combineert en uploads veilig valideert is praktische kennis voor het bouwen van real-world API's die door gebruikers ingediende inhoud accepteren.