وقتی یه Request به API میرسه، همه اطلاعاتش داخل URL یا Body نیست. بخشی از داده‌ها به شکل اطلاعات جانبی همراه درخواست ارسال میشن؛ چیزهایی مثل نوع مرورگر، زبان موردنظر، نوع محتوای ارسالی یا اطلاعات مربوط به احراز هویت. به این بخش از درخواست سربرگ‌های HTTP گفته میشه که اصطلاح رایج اون Header هست.

در FastAPI میشه این اطلاعات رو خیلی راحت دریافت کرد و داخل Endpoint ازشون استفاده کرد. فهم Headerها برای کسی که تازه API میسازه مهمه، چون خیلی از قابلیت‌های واقعی مثل Token، نوع محتوا، Cache و حتی بعضی تنظیمات امنیتی روی همین بخش سوار هستن.

Header در FastAPI چیست؟

هر Request معمولاً سه بخش مهم داره: آدرس درخواست، محتوای اصلی و اطلاعات جانبی. آدرس مشخص میکنه درخواست به کدوم Endpoint میره، محتوای اصلی ممکنه داده فرم یا JSON باشه و Headerها اطلاعاتی درباره خود Request حمل میکنن.

مثلاً مرورگر ممکنه داخل Header مشخص کنه چه نرم‌افزاری درخواست رو ارسال کرده، چه نوع Responseای رو قبول میکنه یا چه Tokenای برای احراز هویت داره. این داده‌ها معمولاً برای منطق اصلی فرم نیستن، ولی روی نحوه پردازش Request تأثیر میذارن.

تفاوت Header با Body و Query چیست؟

مقداری مثل page=2 که برای فیلتر یا صفحه‌بندی ارسال میشه معمولاً داخل Query قرار میگیره، اطلاعات اصلی مثل نام و ایمیل کاربر داخل Body میاد و چیزهایی که درباره خود Request هستن معمولاً داخل Header قرار میگیرن.

مثلاً Token ورود کاربر معمولاً بهتره داخل Header ارسال بشه، چون بخشی از داده اصلی فرم نیست و تقریباً روی چندین Endpoint مختلف استفاده میشه. همین موضوع برای اطلاعاتی مثل نوع مرورگر یا نوع محتوای Request هم صدق میکنه.

دریافت Header در FastAPI

FastAPI ابزار آماده‌ای برای گرفتن Headerها داره و میشه پارامتر موردنظر رو مستقیم داخل تابع Endpoint تعریف کرد.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/profile")
async def get_profile(
    authorization: str | None = Header(default=None),
    user_agent: str | None = Header(default=None)
):
    return {
        "authorization": authorization,
        "user_agent": user_agent
    }

در این مثال دو Header دریافت میشن؛ یکی برای اطلاعات مربوط به احراز هویت و یکی برای مشخصات نرم‌افزاری که Request رو ارسال کرده. FastAPI اسم‌هایی مثل user_agent رو به شکل مناسب با ساختار Headerهای HTTP هماهنگ میکنه.

Token چرا معمولاً داخل Header ارسال می‌شود؟

وقتی کاربر Login میکنه، ممکنه سرور یه Token به اون بده تا در Requestهای بعدی خودش رو معرفی کنه. این Token معمولاً داخل Header مخصوص احراز هویت ارسال میشه که اسمش Authorization هست.

مزیت این روش اینه که اطلاعات احراز هویت از داده اصلی Request جدا میمونه. مثلاً Endpoint ساخت محصول میتونه اطلاعات محصول رو داخل Body دریافت کنه و Token کاربر هم مستقل از اون داخل Header ارسال بشه.

البته فقط دریافت Authorization کافی نیست؛ محتوای اون باید بررسی بشه و معتبر بودن Token هم توسط سیستم احراز هویت پروژه تأیید بشه.

User-Agent چه اطلاعاتی می‌دهد؟

مرورگر یا برنامه‌ای که Request رو ارسال میکنه معمولاً یه Header برای معرفی خودش میفرسته. به این مشخصات User-Agent گفته میشه.

از این اطلاعات میشه برای Logging، تحلیل نوع Client یا بعضی رفتارهای خاص استفاده کرد، ولی نباید بهش به عنوان یه منبع کاملاً قابل اعتماد نگاه کنید. کاربر میتونه مقدار User-Agent رو تغییر بده، پس تصمیم‌های امنیتی مهم نباید فقط بر اساس اون انجام بشن.

Headerهای سفارشی چه کاربردی دارند؟

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

در این حالت میشه Header سفارشی تعریف کرد، ولی بهتره اسم‌ها واضح و قابل‌فهم باشن و فقط اطلاعاتی داخل Header قرار بگیره که واقعاً ماهیت جانبی داره. داده‌های اصلی کسب‌وکار معمولاً بهتره داخل Body یا مسیر مناسب خودشون باشن.

به Header اعتماد کامل نکنید

یکی از نکات مهم اینه که بیشتر Headerهایی که از سمت کاربر میان قابل تغییر هستن. یعنی اگه کسی مقدار خاصی داخل Header فرستاد، نباید صرفاً بر اساس اون فرض کنیم درخواست معتبر یا امنه.

مثلاً وجود Authorization فقط یعنی یه مقدار ارسال شده؛ تا زمانی که Token بررسی نشده، هیچ تضمینی وجود نداره که کاربر واقعی یا مجاز باشه.

همین موضوع درباره User-Agent، IPهای منتقل‌شده از Proxy و Headerهای سفارشی هم صدق میکنه. Header داده ورودی حساب میشه و باید مثل بقیه ورودی‌ها با دقت بررسی بشه.

Header چه زمانی انتخاب مناسبی است؟

اگه داده درباره خود Request باشه و نه محتوای اصلی اون، Header معمولاً جای مناسبیه. Token احراز هویت، نوع محتوای ارسال‌شده، زبان موردنظر و اطلاعات مربوط به Client نمونه‌های معمول هستن.

اما اگر داده‌ای بخشی از عملیات اصلی Endpoint باشه، مثلاً عنوان محصول، قیمت یا متن پیام، معمولاً بهتره داخل Body قرار بگیره. این تفکیک باعث میشه طراحی API قابل‌فهم‌تر و نگهداری اون ساده‌تر بشه.

جمع‌بندی

Header در FastAPI برای دریافت اطلاعات جانبی Request استفاده میشه؛ داده‌هایی مثل Token، نوع Client یا تنظیمات مربوط به نحوه ارتباط که قرار نیست داخل Body یا URL قرار بگیرن. FastAPI با ابزار Header دریافت این اطلاعات رو ساده کرده و میشه اون‌ها رو مستقیماً داخل پارامترهای Endpoint تعریف کرد.

با این حال Headerها هم ورودی کاربر هستن و نباید بدون بررسی بهشون اعتماد کرد. مخصوصاً مقادیری مثل Token باید قبل از استفاده اعتبارسنجی بشن و User-Agent هم بیشتر برای اطلاعات کمکی مناسبه تا تصمیم‌های امنیتی.