موقع ساخت API با FastAPI خیلی زود به یه سؤال ساده میرسیم: چرا بعضی اطلاعات داخل خود آدرس قرار میگیرن، مثل /users/10، ولی بعضی‌ها بعد از علامت ? نوشته میشن، مثل /users?active=true؟

هر دو روش برای فرستادن اطلاعات از طریق URL استفاده میشن، ولی کاربردشون متفاوته. به مقداری که بخشی از مسیر آدرس و معمولاً مشخص‌کننده یک منبع خاصه، پارامتر مسیر یا Path Parameter گفته میشه. در مقابل، اطلاعاتی که برای فیلتر، جستجو یا تنظیم نتیجه ارسال میشن، پارامتر پرس‌وجو یا Query Parameter هستن.

فهم همین تفاوت ساده باعث میشه آدرس‌های API تمیزتر و قابل‌فهم‌تر طراحی بشن.

Path Parameter در FastAPI چیست؟

وقتی یه مقدار مشخص میکنه دقیقاً با کدوم Resource یا منبع کار داریم، معمولاً بهتره داخل مسیر قرار بگیره.

مثلاً:

/users/25

این آدرس یعنی کاربر شماره ۲۵ رو میخوایم. عدد ۲۵ بخشی از هویت منبعه، نه یه فیلتر جانبی.

همین الگو برای محصول، سفارش یا مقاله هم کاربرد داره:

/products/15

/orders/120

پس شناسه‌هایی مثل ID معمولاً گزینه مناسبی برای Path Parameter هستن.

Query Parameter چه کاربردی دارد؟

حالا ممکنه منبع اصلی مشخص باشه، ولی بخوایم نتایج رو محدود یا مرتب کنیم.

مثلاً:

/products?category=laptop

اینجا هنوز درباره لیست محصولات صحبت میکنیم، اما فقط محصولاتی از دسته لپ‌تاپ رو میخوایم.

یا:

/products?page=2

اینجا فقط میگیم صفحه دوم نتایج نمایش داده بشه.

بنابراین چیزهایی مثل جستجو، فیلتر، مرتب‌سازی و تقسیم نتایج به چند صفحه معمولاً Query Parameter هستن.

Path و Query در FastAPI با یک مثال

FastAPI خودش از روی تعریف Route و پارامترهای تابع تشخیص میده هر مقدار از کجا باید دریافت بشه:

from fastapi import FastAPI

app = FastAPI()


@app.get("/products/{product_id}")
async def get_product(product_id: int):
    return {"product_id": product_id}


@app.get("/products")
async def list_products(
    category: str | None = None,
    page: int = 1
):
    return {
        "category": category,
        "page": page
    }

در Endpoint اول، product_id داخل مسیر تعریف شده و آدرسی مثل /products/15 یه محصول مشخص رو انتخاب میکنه.

در Endpoint دوم، category و page بخشی از مسیر نیستن و میشه درخواستی مثل /products?category=phone&page=2 فرستاد.

FastAPI نوع پارامترها را هم بررسی می‌کند

FastAPI فقط مقدار رو از URL نمیگیره؛ نوع داده‌ای که مشخص کردید رو هم بررسی میکنه.

وقتی product_id رو به صورت int تعریف میکنید، یعنی شناسه باید عدد صحیح باشه. اگر مقدار نامعتبر ارسال بشه، FastAPI قبل از رسیدن درخواست به منطق اصلی Endpoint متوجه مشکل میشه.

همین موضوع برای Query Parameterها هم وجود داره. مثلاً اگه page باید عدد باشه، لازم نیست داخل Endpoint خودتون دوباره نوع اون رو دستی بررسی کنید.

Query Parameter می‌تواند اختیاری باشد

یکی از مزیت‌های Query Parameter اینه که خیلی راحت میتونه اختیاری باشه.

مثلاً در مثال بالا category اجباری نیست. بنابراین این آدرس معتبره:

/products

و این یکی هم معتبره:

/products?category=phone

این ویژگی برای فیلترها و جستجو خیلی کاربردیه، چون کاربر میتونه فقط پارامترهایی رو بفرسته که واقعاً لازم داره.

در مقابل، مقدار تعریف‌شده داخل Path معمولاً برای Match شدن همون Route لازمه. مثلاً /products/{product_id} بدون شناسه محصول دیگه همون Endpoint نیست.

اشتباه رایج در طراحی URL

گاهی تمام فیلترها رو داخل مسیر میذاریم و به آدرس‌هایی شبیه این میرسیم:

/products/category/laptop/page/2/order/price

این ساختار خیلی زود شلوغ میشه.

نسخه واضح‌تر میتونه این باشه:

/products?category=laptop&page=2&order=price

از اون طرف، اگه واقعاً یه محصول مشخص رو میخوایم، /products/25 معمولاً واضح‌تر از /products?id=25 هست.

برای انتخاب بین این دو، یه سؤال ساده کافیه:

این مقدار مشخص‌کننده هویت منبعه یا فقط نتیجه رو فیلتر و تنظیم میکنه؟

اگر هویت منبع رو مشخص میکنه، Path انتخاب طبیعی‌تریه. اگر برای فیلتر، جستجو، مرتب‌سازی یا صفحه‌بندیه، Query معمولاً مناسب‌تره.

چند مثال کاربردی

برای گرفتن یه کاربر مشخص:

/users/10

برای جستجوی مقاله:

/articles?search=fastapi

برای نمایش صفحه سوم نتایج:

/articles?page=3&limit=20

برای گرفتن سفارش مشخص:

/orders/150

با همین الگو میشه بخش بزرگی از URLهای یه API معمولی رو تمیز طراحی کرد.

جمع‌بندی

در FastAPI، پارامتر مسیر یا Path Parameter معمولاً برای مشخص کردن یه Resource خاص استفاده میشه؛ مثل شناسه محصول یا کاربر. پارامتر پرس‌وجو یا Query Parameter بیشتر برای فیلتر، جستجو، مرتب‌سازی و صفحه‌بندی کاربرد داره.

FastAPI دریافت و بررسی نوع هر دو رو به شکل ساده انجام میده و Query Parameterها هم میتونن اختیاری باشن.

قاعده‌ای که ارزش یادآوری داره اینه:

هویت Resource داخل Path؛ فیلتر و تنظیم نتیجه داخل Query.