Request Models dan Validation

Endpoint POST pada chapter sebelumnya menerima body dict mentah — JSON tanpa field judul, dengan selesai berupa string, bahkan body kosong, semuanya diterima tanpa protes. Input yang kotor seperti ini akan merembet ke penyimpanan, merusak data, dan baru meledak sebagai bug di sisi klien. Yang kita butuhkan adalah kontrak tegas di pintu masuk: struktur field, tipe, dan batasan nilai yang diperiksa sebelum fungsi rute dijalankan. FastAPI menyerahkan tugas ini ke library Pydantic (versi 2.12 terpasang di lingkungan pengujian): kita mendeklarasikan sebuah class BaseModel, dan setiap request body yang tidak sesuai ditolak otomatis dengan status 422.

BaseModel sebagai Kontrak Request #

Request model dideklarasikan seperti class Python biasa dengan type hints — materi yang berakar di Section Type Hints dan Static Analysis:

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field


class TugasBaru(BaseModel):
    judul: str = Field(min_length=3, max_length=100)
    prioritas: int = Field(default=1, ge=1, le=5)
    catatan: str | None = None


app = FastAPI()


@app.post("/tugas", status_code=201)
def buat_tugas(tugas: TugasBaru):
    return {"id": 1, **tugas.model_dump()}


client = TestClient(app)

r = client.post("/tugas", json={"judul": "Belajar Pydantic"})
print(r.status_code, r.json())

r = client.post("/tugas", json={"judul": "Belajar REST", "prioritas": 2, "catatan": "Sore ini"})
print(r.status_code, r.json())

Output yang Dihasilkan:

201 {'id': 1, 'judul': 'Belajar Pydantic', 'prioritas': 1, 'catatan': None}
201 {'id': 1, 'judul': 'Belajar REST', 'prioritas': 2, 'catatan': 'Sore ini'}

Mari kita telaah perannya satu per satu:

1. Baris 6 (class TugasBaru(BaseModel)): class Pydantic menggantikan dict mentah pada chapter sebelumnya sebagai tipe parameter tugas; FastAPI mem-parse, memvalidasi, dan mengonversi body JSON menjadi instance class ini.
2. Baris 7 (judul: str = Field(...)): field tanpa nilai default berarti wajib — request tanpa judul ditolak.
3. Baris 8 (prioritas: int = Field(default=1, ...)): field boleh dilewatkan klien; nilai 1 terisi otomatis, terlihat pada output pertama.
4. Baris 9 (catatan: str | None = None): pola Optional standar — hadir sebagai None saat tidak dikirim.
5. Baris 15 (@app.post("/tugas", status_code=201)): parameter status_code mengubah baris status dari default 200 menjadi 201 Created — aturan kapan tiap kode dipakai dibahas di chapter Status Codes dan Error Responses.
6. Baris 17 (tugas.model_dump()): method bawaan Pydantic mengubah instance menjadi dictionary — berguna saat kita perlu menggabungkannya dengan field lain seperti id.

Field Wajib, Default, dan Optional #

Ketiga status field di atas punya makna yang berbeda dan tidak saling menggantikan:

Perbedaan ketiganya sering membuat bingung: nilai default mengisi field yang hilang, sedangkan str | None juga mengizinkan klien mengirim "catatan": null secara eksplisit. Pilih str | None = None hanya saat None memang nilai yang bermakna.

Constraint Validasi dan Error 422 #

Field() tidak hanya mengatur default — parameter constraint-nya membatasi nilai yang diterima: min_length/max_length untuk string dan collection, gt/ge/lt/le untuk angka. Mari kita kirim body yang melanggar kontrak:

r = client.post("/tugas", json={"prioritas": 2})
print(r.status_code, r.json())

r = client.post("/tugas", json={"judul": "OK", "prioritas": 9})
print(r.status_code, r.json())

Output yang Dihasilkan:

422 {'detail': [{'type': 'missing', 'loc': ['body', 'judul'], 'msg': 'Field required', 'input': {'prioritas': 2}}]}
422 {'detail': [{'type': 'string_too_short', 'loc': ['body', 'judul'], 'msg': 'String should have at least 3 characters', 'input': 'OK', 'ctx': {'min_length': 3}}, {'type': 'less_than_equal', 'loc': ['body', 'prioritas'], 'msg': 'Input should be less than or equal to 5', 'input': 9, 'ctx': {'le': 5}}]}

Kedua response berstatus 422 Unprocessable Entity — kode yang dipilih FastAPI untuk “body diterima tapi gagal validasi”. Setiap item pada list detail memuat empat kunci: type (jenis pelanggaran), loc (lokasi field, misalnya ['body', 'judul']), msg (pesan untuk manusia), dan input (nilai yang ditolak). Perhatikan bahwa response kedua memuat dua pelanggaran sekaligus — judul terlalu pendek dan prioritas melebihi 5 — dikumpulkan dalam satu penolakan, bukan dihentikan di pelanggaran pertama.

Validasi ini juga terdokumentasi sendiri: constraint min_length=3 pada contoh di atas muncul sebagai minLength di skema OpenAPI dan halaman /docs — kita lihat caranya di chapter OpenAPI dan API Documentation. Sebelum itu, chapter Response Models mengurus sisi keluaran agar field internal tidak ikut bocor ke klien.