ساخت API با FastAPI: راهنمای کامل برای مبتدیان (۲۰۲۶)

تا اینجا با پایتون ربات ساختیم، داده اسکرپ کردیم و حتی هوش مصنوعی وصل کردیم. اما همه‌ی این پروژه‌ها دیر یا زود به یک نیاز مشترک می‌رسن: یک API که بقیه‌ی سرویس‌ها (ربات، اپ موبایل، یا حتی n8n) بتونن باهاش حرف بزنن. FastAPI یکی از سریع‌ترین و لذت‌بخش‌ترین راه‌ها برای ساخت چنین APIـیه — و توی این راهنما یک API واقعی برای مدیریت محصولات فروشگاه می‌سازیم.

فهرست مطالب

• FastAPI چیست و چرا این‌قدر محبوبه؟
• پیش‌نیازها
• مرحله ۱: نصب و اولین API
• مرحله ۲: پارامترهای مسیر و کوئری
• مرحله ۳: تعریف مدل داده با Pydantic
• مرحله ۴: ساخت API کامل مدیریت محصول (CRUD)
• مرحله ۵: مستندات خودکار — رایگان و بدون هیچ کدی
• مرحله ۶: وصل‌کردن این API به ربات یا n8n
• جدول مقایسه: FastAPI در برابر Flask و Django
• اشتباهات رایج
• سوالات متداول

FastAPI چیست و چرا این‌قدر محبوبه؟

FastAPI یک فریم‌ورک پایتونیه برای ساخت API، که بر پایه‌ی Type Hint‌های خودِ پایتون کار می‌کنه. یعنی همون‌طور که نوع متغیرها رو در کدتون مشخص می‌کنید (name: str)، FastAPI خودش اعتبارسنجی داده، تبدیل نوع و حتی مستندات API رو خودکار می‌سازه. از نظر سرعت اجرا هم، در کنار Node.js و Go قرار می‌گیره — چیزی که کمتر فریم‌ورک پایتونی دیگه‌ای بهش می‌رسه.

پیش‌نیازها

• آشنایی پایه با پایتون و مفهوم تابع
• پایتون ۳.۱۰ به بالا

pip install fastapi uvicorn

مرحله ۱: نصب و اولین API

یک فایل به اسم main.py بسازید:

from fastapi import FastAPI

app = FastAPI(title="فروشگاه API")

@app.get("/")
async def read_root():
    return {"message": "به API فروشگاه خوش آمدید"}

حالا سرور رو اجرا کنید:

uvicorn main:app --reload

با باز‌کردن http://127.0.0.1:8000 پیام خوش‌آمد رو می‌بینید. پرچم --reload باعث می‌شه با هر تغییر در کد، سرور خودش دوباره راه بیفته — خیلی مناسب برای توسعه.

مرحله ۲: پارامترهای مسیر و کوئری

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

@app.get("/search/")
async def search(q: str, limit: int = 10):
    return {"query": q, "limit": limit}

نکته‌ی جادویی: چون نوشتید product_id: int، اگه کسی مقدار غیرعددی بفرسته (مثلاً /products/abc)، FastAPI خودش خطای ۴۲۲ با توضیح دقیق برمی‌گردونه — بدون این‌که شما حتی یک خط کد اعتبارسنجی نوشته باشید.

مرحله ۳: تعریف مدل داده با Pydantic

برای داده‌های پیچیده‌تر (مثل ثبت یک محصول کامل)، از یک مدل Pydantic استفاده می‌کنیم:

from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float
    in_stock: bool = True
    description: str | None = None

این مدل هم ساختار داده رو مشخص می‌کنه، هم به‌صورت خودکار هر درخواستی که بهش نرسه رو رد می‌کنه.

مرحله ۴: ساخت API کامل مدیریت محصول (CRUD)

حالا همه‌چیز رو کنار هم می‌ذاریم و یک API کامل با چهار عملیات پایه (ایجاد، خواندن، ویرایش، حذف) می‌سازیم:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI(title="فروشگاه API")

class Product(BaseModel):
    name: str
    price: float
    in_stock: bool = True

products: dict[int, Product] = {}
next_id = 1

@app.post("/products/")
async def create_product(product: Product):
    global next_id
    products[next_id] = product
    next_id += 1
    return {"id": next_id - 1, **product.model_dump()}

@app.get("/products/")
async def list_products():
    return products

@app.get("/products/{product_id}")
async def get_product(product_id: int):
    if product_id not in products:
        raise HTTPException(status_code=404, detail="محصول پیدا نشد")
    return products[product_id]

@app.put("/products/{product_id}")
async def update_product(product_id: int, product: Product):
    if product_id not in products:
        raise HTTPException(status_code=404, detail="محصول پیدا نشد")
    products[product_id] = product
    return product

@app.delete("/products/{product_id}")
async def delete_product(product_id: int):
    if product_id not in products:
        raise HTTPException(status_code=404, detail="محصول پیدا نشد")
    del products[product_id]
    return {"message": "محصول حذف شد"}

نکته‌ی مهم: این نسخه داده رو فقط در حافظه (یک دیکشنری پایتون) نگه می‌داره — یعنی با هر بار ری‌استارت سرور، همه‌چیز پاک می‌شه. برای پروژه‌ی واقعی باید products رو با یک دیتابیس واقعی (مثل PostgreSQL) جایگزین کنید.

مرحله ۵: مستندات خودکار — رایگان و بدون هیچ کدی

همین الان به آدرس http://127.0.0.1:8000/docs برید. یک رابط تعاملی کامل (Swagger UI) می‌بینید که همه‌ی endpointهای بالا رو نشون می‌ده و حتی می‌تونید مستقیم از همون صفحه تستشون کنید — بدون نوشتن حتی یک خط مستندات دستی. نسخه‌ی جایگزین و ساده‌ترش هم در /redoc در دسترسه.

مرحله ۶: وصل‌کردن این API به ربات یا n8n

حالا که یک API واقعی دارید، می‌تونید از هر جای دیگه‌ای بهش وصل بشید. برای مثال، دقیقاً مثل الگویی که در آموزش n8n دیدیم، کافیه یک گره HTTP Request به آدرس http://your-server:8000/products/ اضافه کنید تا لیست محصولاتتون رو مستقیم داخل یک ورک‌فلوی خودکار بگیرید. یا حتی می‌تونید ربات بله‌ای که در مقاله‌ی ساخت ربات بله ساختیم رو طوری تغییر بدید که به‌جای پاسخ ثابت، موجودی واقعی محصول رو از همین API بخونه.

جدول مقایسه: FastAPI در برابر Flask و Django

اشتباهات رایج

• فراموش‌کردن async بدون نیاز واقعی: اگه داخل تابع از کتابخانه‌ای استفاده می‌کنید که async نیست، تعریف تابع به‌صورت async def فایده‌ی عملکردی نداره و می‌تونه گمراه‌کننده باشه.
• نگه‌داشتن داده در حافظه برای پروژه‌ی واقعی: همون‌طور که دیدیم، دیکشنری پایتون فقط برای یادگیریه؛ فراموش نکنید قبل از انتشار واقعی، دیتابیس اضافه کنید.
• عدم استفاده از HTTPException برای خطاها: برگردوندن یک دیکشنری ساده به‌جای raise HTTPException، کد وضعیت HTTP درست (مثل ۴۰۴) رو به کلاینت نمی‌رسونه.

سوالات متداول

آیا FastAPI برای پروژه‌های واقعی و بزرگ هم مناسبه؟

بله؛ شرکت‌های بزرگی مثل Uber و Netflix از FastAPI در بخش‌هایی از زیرساختشون استفاده می‌کنن.

آیا نیاز به دیتابیس دارم؟

برای یادگیری نه، ولی برای هر پروژه‌ی واقعی بله — معمولاً با PostgreSQL یا SQLite همراه با ابزاری مثل SQLAlchemy.

آیا می‌تونم این API رو با ربات بله یا روبیکای خودم وصل کنم؟

بله، دقیقاً همون‌طور که در بخش مرحله ۶ دیدیم — کافیه از داخل کد ربات، به آدرس API با requests درخواست بزنید.

اگه نمی‌خوام خودم زیرساخت رو مدیریت کنم چیکار کنم؟

تیم ما می‌تونه هم API اختصاصی‌تون رو بسازه، هم میزبانی و نگهداریش رو انجام بده — کافیه با ما تماس بگیرید.

جمع‌بندی

حالا می‌دونید چطور یک API واقعی، با مستندات خودکار و اعتبارسنجی کامل، از صفر بسازید — و چطور به پروژه‌های قبلی‌تون (ربات بله، n8n) وصلش کنید. اگه برای طراحی و پیاده‌سازی یک API اختصاصی برای کسب‌وکارتون به کمک نیاز دارید، تیم ما آماده‌ی همراهیه.