Belajar FastAPI - Routing & Path Parameters

#Pendahuluan

Setelah di episode 3 kalian berhasil menjalankan aplikasi FastAPI pertama dan melihat auto-docs bekerja, sekarang kita naik satu level: routing lengkap. REST API dibangun dari operasi standar terhadap resource — ini yang membedakan aplikasi yang hanya menampilkan teks dengan aplikasi yang benar-benar melayani data.

Mengapa episode ini penting? Karena hampir semua bug routing yang ditemukan di produksi — endpoint yang tidak ketemu, parameter yang salah tipe, atau path yang bentrok — berakar pada kurangnya pemahaman tiga hal yang akan kita bahas: HTTP methods, path vs query parameters, dan urutan deklarasi.

#Empat HTTP Methods Inti

FastAPI menyediakan dekorator untuk setiap HTTP method. Pola umum pada resource items:

main.py - CRUD routing

from fastapi import FastAPI
 
app = FastAPI()
 
ITEMS = {1: "Keyboard", 2: "Mouse"}
 
 
@app.get("/items/{item_id}")
def get_item(item_id: int) -> dict:
    return {"item_id": item_id, "name": ITEMS[item_id]}
 
 
@app.post("/items/")
def create_item(name: str) -> dict:
    new_id = max(ITEMS) + 1
    ITEMS[new_id] = name
    return {"item_id": new_id, "name": name}
 
 
@app.put("/items/{item_id}")
def update_item(item_id: int, name: str) -> dict:
    ITEMS[item_id] = name
    return {"item_id": item_id, "name": name}
 
 
@app.delete("/items/{item_id}")
def delete_item(item_id: int) -> dict[str, bool]:
    del ITEMS[item_id]
    return {"ok": True}

Perhatikan pola semantiknya:

Status code akan kita bahas detail di episode 7 — di episode ini kita fokus pada pemetaan URL dan parameter.

#Path Parameters: Validasi Tipe

Path parameter adalah bagian dari URL yang dinamis, dideklarasikan dengan kurung kurawal di string path:

Path parameter dengan tipe

@app.get("/items/{item_id}")
def get_item(item_id: int) -> dict:
    return {"item_id": item_id}

{item_id} di path dipasangkan dengan parameter item_id: int di fungsi. FastAPI lalu:

1. Mengekstrak nilai item_id dari URL.
2. Mengkonversi ke int — request /items/42 menghasilkan 42 bertipe int.
3. Menolak dengan 422 jika tidak bisa dikonversi — request /items/abc.

Urutan parameter penting di sini: FastAPI mengenali path parameter dari nama yang cocok dengan kurung kurawal di path. Semua parameter fungsi lain secara otomatis dianggap query parameter.

#Query Parameters

Query parameters adalah pasangan key=value setelah tanda ? di URL, dan dideklarasikan cukup dengan parameter fungsi biasa:

Query parameters dengan default

@app.get("/items/")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None) -> dict:
    return {"skip": skip, "limit": limit, "q": q}

URL /items/?skip=0&limit=5&q=keyboard menghasilkan skip=0, limit=5, q="keyboard". Aturan yang perlu dipahami:

• Parameter dengan default → query param opsional.
• Parameter tanpa default → query param wajib (/items/ tanpa skip akan error 422).

Tipe str | None = None (Python 3.10+) memberi tahu FastAPI bahwa parameter ini opsional dan boleh null — representasi ini adalah gaya modern yang direkomendasikan menggantikan Optional[str].

#Parameter Ordering: Pitfall Klasik

Python menuntut parameter wajib sebelum parameter berdefault. FastAPI menambahkan satu lapis aturan lagi — path parameter harus di deklarasikan lebih dulu jika ada query param opsional setelahnya. Perhatikan dua kasus:

Parameter ordering yang benar

@app.get("/users/{user_id}/items/{item_id}")
def read_user_item(
    user_id: int,
    item_id: int,
    q: str | None = None,
) -> dict:
    return {"user_id": user_id, "item_id": item_id, "q": q}

Ini valid: path params (user_id, item_id) lebih dulu, lalu query param opsional (q). Yang sering menjebak adalah menaruh parameter tanpa default setelah parameter berdefault — Python sendiri akan melempar SyntaxError.

#Constraint Parameter dengan Path dan Query

Dari episode ini kita mulai memakai Path dan Query — objek FastAPI untuk menambahkan constraint dan metadata:

Constraint path dan query

from fastapi import FastAPI, Path, Query
 
app = FastAPI()
 
 
@app.get("/items/{item_id}")
def get_item(
    item_id: int = Path(ge=1, description="ID item, minimal 1"),
    q: str | None = Query(default=None, max_length=50, description="Kata kunci"),
) -> dict:
    return {"item_id": item_id, "q": q}

• Path(ge=1) — item_id harus >= 1, jika tidak → 422.
• Query(max_length=50) — q maksimal 50 karakter.

Constraint ini bukan hanya dokumentasi — FastAPI menjadikannya bagian dari schema OpenAPI dan menjalankan validasinya saat runtime.

#Path vs Query: Ringkasan

#Penutup

Inti yang harus dibawa pulang:

• Empat dekorator inti: @app.get / @app.post / @app.put / @app.delete.
• Path parameter = dari kurung kurawal URL, otomatis divalidasi & dikonversi sesuai tipe.
• Query parameter = parameter fungsi biasa; default menentukan opsional/wajib.
• Urutan deklarasi: path param lebih dulu, query opsional di belakang.
• Path dan Query menambahkan constraint + metadata yang masuk ke OpenAPI.

Di episode 5 selanjutnya kita akan membahas Pydantic models & validation — jantung validasi FastAPI. Kalian akan belajar mendefinisikan request/response schema, nested models, constraint Field, serta field_validator dan model_validator untuk aturan lintas field. Ini fondasi untuk semua episode database berikutnya!