ساخت api با پایتون

اولین API جدی که نوشتم، یک سرویس کوچک برای همگام‌سازی موجودی بین دو سیستم بود. با Flask در یک بعدازظهر آماده شد و همه‌چیز خوب پیش می‌رفت تا دو ماه بعد که تیم موبایل خواست نسخه‌ی جدیدی از خروجی را اضافه کنیم. آن‌جا بود که فهمیدم تصمیم‌های کوچکِ آن بعدازظهر — نزدن نسخه به مسیرها، نبود مستندسازی، نبود اعتبارسنجی ورودی — در ماه ششم پروژه، به یک بازنویسی کامل تبدیل شدند. این تجربه برایم درس مهمی داشت: ساخت API با پایتون نه فقط نوشتن چند مسیر و برگرداندن JSON است؛ یک فرآیند طراحی است که از روز اول باید درست چیده شود تا با رشد مصرف‌کننده‌هایش جان سالم به در ببرد. در این مقاله، همان مسیری را می‌روم که امروز با تیم‌ها و مشتریانم طی می‌کنم: از انتخاب چارچوب و اولین endpoint تا اعتبارسنجی، احراز هویت، نسخه‌بندی، مستندسازی و استقرار.

چرا پایتون برای ساخت API؟

اگر با مفاهیم پایه‌ی پایتون آشنا نیستید، اول آموزش پایتون از صفر را بخوانید. اما اگر پایتون را می‌شناسید و به فکر ساخت API هستید، این سوال پیش می‌آید که چرا پایتون و نه Node.js یا Go یا PHP. در تجربه‌ی من، سه دلیل مشخص پایتون را جلو می‌اندازد:

• هم‌جواری با داده و هوش مصنوعی: اگر API شما قرار است با مدل یادگیری ماشین، پردازش داده، یا کتابخانه‌هایی مثل pandas کار کند، پایتون در همان بستر خانه‌ی اولش است. یک API که مدل زبانی را سرو می‌کند، در پایتون چند برابر طبیعی‌تر است.
• اکوسیستم چارچوب‌ها: Flask، FastAPI و Django REST Framework، هر کدام یک رویکرد متفاوت را پوشش می‌دهند. از پروژه‌ی کوچک تا پلتفرم بزرگ، ابزار مناسب وجود دارد.
• خوانایی و نگهداری: کد پایتون در تیم‌های چندنفره، خواناتر از بسیاری از گزینه‌ها است. این یک مزیت کوچک به‌نظر می‌رسد، ولی در پروژه‌هایی که ماه‌ها روی آن‌ها کار می‌شود، اثرش محسوس است.

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

API، قرارداد بین دو برنامه است؛ اگر این قرارداد از روز اول شفاف و نسخه‌بندی‌شده نباشد، هر تغییر کوچک، یک بحران برای مصرف‌کننده‌هایش می‌شود.

انتخاب چارچوب: Flask، FastAPI یا Django REST Framework

سه گزینه‌ی اصلی برای ساخت API در پایتون وجود دارد. انتخاب درست، بیشتر از هر چیز به اندازه و ماهیت پروژه بستگی دارد:

انتخاب من در پروژه‌های واقعی: برای API کوچک و ابزار داخلی، Flask یا FastAPI؛ برای پروژه‌هایی که با ORM پیچیده و روابط زیاد سر و کار دارند، Django REST Framework. اگر تازه با جنگو آشنا می‌شوید، آموزش جنگو برای مبتدیان مسیر پایه را نشان می‌دهد و در ادامه‌ی همان، DRF یک قدم طبیعی است. اگر سبک و انعطاف‌پذیر را ترجیح می‌دهید، آموزش فلاسک در پایتون نقطه‌ی شروع خوبی است — در این مقاله، ابتدا روی Flask مثال می‌زنم چون راحت‌ترین نقطه‌ی ورود است، و بعد FastAPI را با معادل‌هایش می‌آورم.

یک نکته‌ی ظریف که در پروژه‌های واقعی زیاد دیده‌ام: بعضی تیم‌ها به‌دلیل «محبوبیت» یک چارچوب را انتخاب می‌کنند و بعد در ماه سوم متوجه می‌شوند که ساختار آن، با نیازهای پروژه‌شان نمی‌خواند. قبل از انتخاب، فهرست نیازهای واقعی (نیاز به async، نیاز به ORM، نیاز به پنل ادمین، نیاز به مستندسازی خودکار) را بنویسید و بعد چارچوب را انتخاب کنید.

نصب و اولین endpoint

مثل هر پروژه‌ی پایتونی، از یک محیط مجازی شروع کنید:

python -m venv venv
source venv/bin/activate        # در ویندوز: venv\Scripts\activate

pip install flask
pip freeze > requirements.txt

ساده‌ترین API، با یک endpoint شروع می‌شود:

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/api/health", methods=["GET"])
def health_check():
    return jsonify({"status": "ok"})

if __name__ == "__main__":
    app.run(debug=True)

با اجرای python app.py، سرویس شما روی http://127.0.0.1:5000/api/health بالا می‌آید. یک نکته‌ی مهم: سرور توسعه‌ی Flask، هرگز برای تولید مناسب نیست. همان‌طور که در ادامه توضیح می‌دهم، در محیط تولید باید از Gunicorn یا uWSGI پشت یک reverse proxy مثل Nginx استفاده کنید.

معادل همین endpoint در FastAPI، کمی متفاوت است ولی همان ایده را دارد:

from fastapi import FastAPI

app = FastAPI()

@app.get("/api/health")
def health_check():
    return {"status": "ok"}

اگر با کار با JSON در پایتون راحت نیستید، JSON چیست و چطور داده‌ها را ساختاردهی می‌کند مبانی را روشن می‌کند — چون تمام API شما، در نهایت به خواندن و نوشتن JSON می‌رسد.

HTTP Methods و طراحی منابع

در طراحی API، هر منبع (resource) با یک نام جمع مشخص می‌شود و HTTP Methods، عملیات را تعیین می‌کنند:

چهار الگوی طراحی که در پروژه‌های واقعی به‌کارم آمده:

• اسم جمع برای مسیرها: /api/posts نه /api/post. این قرارداد، انتظار مصرف‌کننده را برآورده می‌کند.
• شناسه در مسیر، نه در query: GET /api/posts/1 خوانا‌تر از GET /api/posts?id=1 است. query را برای فیلتر و صفحه‌بندی نگه دارید.
• پیوندهای تودرتو برای روابط: GET /api/users/1/posts نشان می‌دهد که پست‌ها متعلق به کاربر ۱ هستند. این الگو، در سطح روابط، خواناتر از فیلتر است.
• استفاده از DELETE و PATCH به‌جای POST در همه‌جا: خیلی از تیم‌ها برای همه‌ی عملیات از POST استفاده می‌کنند. این کار، سادگی ظاهری می‌دهد ولی مزیت‌های کش، idempotency و خوانایی HTTP را از دست می‌دهد.

@app.route("/api/posts", methods=["GET"])
def list_posts():
    return jsonify([...])

@app.route("/api/posts", methods=["POST"])
def create_post():
    data = request.get_json()
    # ساخت منبع جدید
    return jsonify({"id": 1}), 201

@app.route("/api/posts/<int:post_id>", methods=["GET"])
def get_post(post_id):
    return jsonify({...})

@app.route("/api/posts/<int:post_id>", methods=["PATCH"])
def update_post(post_id):
    return jsonify({...})

@app.route("/api/posts/<int:post_id>", methods=["DELETE"])
def delete_post(post_id):
    return "", 204

اعتبارسنجی ورودی با Pydantic

در API، هرگز به داده‌ی ورودی اعتماد نکنید. FastAPI با Pydantic، این کار را بسیار ساده کرده. در Flask، می‌توانید از همان Pydantic به‌طور مستقل استفاده کنید:

from pydantic import BaseModel, EmailStr, Field, validator
from datetime import datetime

class PostCreate(BaseModel):
    title: str = Field(..., min_length=3, max_length=200)
    body: str = Field(..., min_length=10)
    email: EmailStr
    published_at: datetime | None = None

    @validator("title")
    def title_must_not_be_blank(cls, v):
        if not v.strip():
            raise ValueError("title cannot be blank")
        return v.strip()

و در FastAPI، این مدل مستقیم در امضای endpoint استفاده می‌شود:

@app.post("/api/posts", status_code=201)
def create_post(post: PostCreate):
    # post حالا یک شیء معتبر از نوع PostCreate است
    return {"id": 1, "title": post.title}

در Flask، اعتبارسنجی را دستی صدا می‌زنید:

from pydantic import ValidationError

@app.route("/api/posts", methods=["POST"])
def create_post():
    try:
        payload = PostCreate(**request.get_json())
    except ValidationError as e:
        return jsonify({"errors": e.errors()}), 422

    # ادامه پردازش
    return jsonify({"id": 1, "title": payload.title}), 201

مزیت Pydantic در پروژه‌های واقعی، سه چیز است:

• اعتبارسنجی از یک نقطه‌ی متمرکز: قواعد در مدل تعریف می‌شوند و در همه‌ی endpointها استفاده می‌شوند.
• پیام‌های خطای خودکار: مصرف‌کننده دقیقاً می‌فهمد کدام فیلد معتبر نبوده. اگر با ساخت فرم تماس در بستر دیگری آشنا هستید، ساخت فرم تماس با PHP نمونه‌ی مشابهی از اعتبارسنجی دستی را نشان می‌دهد که در پایتون با Pydantic ساده‌تر می‌شود.
• مستندسازی خودکار: در FastAPI، همان مدل Pydantic به‌عنوان تعریف OpenAPI استفاده می‌شود و در Swagger UI نمایش داده می‌شود.

یک نکته‌ی مهم در اعتبارسنجی ورودی: همیشه داده را پاک‌سازی کنید، نه فقط اعتبارسنجی. برای مثال، فیلد email را با نوع EmailStr تعریف کنید تا Pydantic خودش نرمال‌سازی کند. یا برای رشته‌ها، strip را در validator بزنید تا فاصله‌های اضافی حذف شوند. این جزئیات کوچک، در APIهای واقعی، تفاوت بین داده‌ی تمیز و داده‌ی نامرتب را می‌سازد.

در API، هر ورودی، یک ادعای بی‌مدرک است؛ اعتبارسنجی، فرآیند سنجش این ادعا قبل از پذیرش آن است.

کد وضعیت HTTP و مدیریت خطا

در API، بازگرداندن کد وضعیت درست، همان‌قدر مهم است که محتوای پاسخ. جدول زیر، کدهایی است که در پروژه‌های واقعی دائماً استفاده می‌کنم:

تفاوت مهمی که در پروژه‌های واقعی زیاد دیده‌ام: 401 و 403 با هم اشتباه گرفته می‌شوند. 401 یعنی «هویت خود را ثابت نکرده‌اید» و 403 یعنی «هویت شما شناخته شده، ولی اجازه‌ی این کار را ندارید». تفاوت این دو، در تجربه‌ی کلاینت، بسیار مهم است — چون کلاینت در 401 باید به صفحه‌ی ورود برود، ولی در 403 بهتر است پیام «دسترسی ندارید» نشان دهد.

مدیریت خطای متمرکز، الگویی است که در تمام APIهای جدی به‌کار می‌برم. در Flask:

from flask import jsonify
from werkzeug.exceptions import HTTPException

@app.errorhandler(Exception)
def handle_error(e):
    if isinstance(e, HTTPException):
        return jsonify({
            "error": e.name,
            "message": e.description,
            "status": e.code,
        }), e.code

    # خطاهای غیرمنتظره را لاگ کنید ولی جزئیات را به کاربر ندهید
    app.logger.exception("Unexpected error")
    return jsonify({
        "error": "Internal Server Error",
        "status": 500,
    }), 500

در FastAPI، همین کار با HTTPException و exception_handler انجام می‌شود و می‌توانید مدل‌های خطا را هم برای مستندسازی خودکار تعریف کنید. اصول کلی مدیریت خطا، مشابه همان چیزی است که در مدیریت خطا در پایتون به‌عنوان الگوی Fail Fast توضیح داده‌ام — فقط در API، خطا به‌جای استثنا، به کد وضعیت و پیام تبدیل می‌شود.

اتصال به دیتابیس

اکثر APIهای واقعی، داده را از یک دیتابیس می‌خوانند یا در آن ذخیره می‌کنند. اگر با MySQL کار می‌کنید، اتصال پایتون به MySQL مسیر کامل را با جزئیات پارامتریک‌سازی و تراکنش نشان می‌دهد. اگر تازه با SQL آشنا می‌شوید، آموزش MySQL از صفر پیش‌نیاز خوبی است.

سه الگوی اتصال که در پروژه‌های واقعی به‌کارم آمده:

۱) اتصال مستقیم با PyMySQL

import pymysql
from flask import g

def get_db():
    if "db" not in g:
        g.db = pymysql.connect(
            host="localhost",
            user="db_user",
            password="db_password",
            database="my_database",
            charset="utf8mb4",
            cursorclass=pymysql.cursors.DictCursor,
        )
    return g.db

@app.teardown_appcontext
def close_db(exception):
    db = g.pop("db", None)
    if db is not None:
        db.close()

الگوی g در Flask، اتصال دیتابیس را در طول یک درخواست نگه می‌دارد و در پایان، خودکار می‌بندد. این سادگی در پروژه‌های کوچک، عالی است.

۲) ORM با SQLAlchemy

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import declarative_base, sessionmaker

Base = declarative_base()

class Post(Base):
    __tablename__ = "posts"

    id = Column(Integer, primary_key=True)
    title = Column(String(200), nullable=False)
    body = Column(String, nullable=False)

engine = create_engine(
    "mysql+pymysql://user:pass@localhost/mydb?charset=utf8mb4",
    pool_pre_ping=True,
)

Session = sessionmaker(bind=engine)

اگر با مفهوم ORM آشنا نیستید، ORM چیست و چگونه کار با دیتابیس را ساده می‌کند تفاوت آن با کوئری خام را روشن می‌کند. یک هشدار: در FastAPI، الگوی درست استفاده از session با Dependency Injection است — نه به‌شکل global. اگر با این الگو آشنا نیستید، در مستندات رسمی FastAPI نمونه‌های کاملی وجود دارد.

۳) چالش N+1 و راه‌حل آن

یکی از رایج‌ترین مشکلات کارایی در APIهای واقعی، N+1 است: وقتی یک لیست از منابع را برمی‌گردانید و برای هرکدام یک کوئری جدا می‌زنید. در SQLAlchemy، با joinedload یا selectinload حل می‌شود:

from sqlalchemy.orm import joinedload

posts = (
    session.query(Post)
    .options(joinedload(Post.author))
    .all()
)

اگر با pandas کار می‌کنید و داده را از دیتابیس می‌خوانید، pd.read_sql روی همان connection کار می‌کند و مسیر تحلیل داده را در کتابخانه pandas در پایتون توضیح داده‌ام. این ترکیب در APIهای تحلیلی بسیار به‌کار می‌آید.

احراز هویت API

در API، احراز هویت با web معمولی متفاوت است. سه روش رایج که در پروژه‌های واقعی به‌کارم آمده:

۱) API Key در Header

from functools import wraps
from flask import request, jsonify

API_KEYS = {"client-a-key", "client-b-key"}

def require_api_key(f):
    @wraps(f)
    def wrapper(*args, **kwargs):
        key = request.headers.get("X-API-Key")
        if key not in API_KEYS:
            return jsonify({"error": "Invalid API key"}), 401
        return f(*args, **kwargs)
    return wrapper

@app.route("/api/posts")
@require_api_key
def list_posts():
    return jsonify([...])

API Key برای احراز هویت سرویس‌به‌سرویس مناسب است. ولی برای اپلیکیشن‌های کاربرمحور که از سمت مرورگر می‌آیند، انتخاب درستی نیست — چون کلید در کد کلاینت فاش می‌شود.

۲) JWT برای کاربرمحور

import jwt
from datetime import datetime, timedelta

def create_token(user_id):
    payload = {
        "user_id": user_id,
        "exp": datetime.utcnow() + timedelta(hours=1),
    }
    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")

def verify_token(token):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        return payload["user_id"]
    except jwt.ExpiredSignatureError:
        return None
    except jwt.InvalidTokenError:
        return None

تفاوت احراز هویت و مجوزدهی را جدی بگیرید — تفاوت احراز هویت و مجوزدهی این تفکیک را روشن می‌کند. برای درک عمیق‌تر JWT و کاربردهایش، JWT چیست و چه کاربردی در احراز هویت دارد و پیاده‌سازی JWT در APIهای مدرن مکمل‌های طبیعی این بحث هستند.

۳) OAuth2 برای سرویس‌های خارجی

اگر API شما قرار است از طرف کاربر به سرویس دیگری دسترسی داشته باشد (مثل گوگل)، OAuth2 انتخاب درست است. این معماری، پیچیده‌تر از JWT است ولی در سناریوهایی که کاربر می‌خواهد دسترسی به داده‌هایش در سرویس دیگری را به اپلیکیشن شما بدهد، استاندارد است. برای مقایسه‌ی این دو رویکرد، انتخاب بین OAuth و JWT برای پروژه راهنمای تصمیم خوبی است. برای اصول کلی امنیت API، امنیت API و احراز هویت در REST API نکات تکمیلی دارند.

سه نکته‌ی امنیتی که در پروژه‌های واقعی به آن‌ها رسیده‌ام:

• همیشه از HTTPS استفاده کنید: توکن در HTTP بدون رمزنگاری، در شبکه قابل رهگیری است.
• توکن را با انقضای کوتاه صادر کنید: برای JWT، یک ساعت معمولاً کافی است. اگر نیاز به نشست طولانی دارید، از refresh token استفاده کنید.
• هدرهای امنیتی را تنظیم کنید: Strict-Transport-Security، X-Content-Type-Options و Content-Security-Policy. اصول کامل این هدرها در هدرهای امنیتی HTTP آمده است.

نسخه‌بندی: تصمیمی که بعداً گران می‌شود

نسخه‌بندی API، تصمیمی است که اگر از روز اول گرفته نشود، در آینده به یک بحران تبدیل می‌شود. سه الگوی اصلی:

انتخاب من: برای پروژه‌های داخلی و APIهایی که کلاینت‌ها تحت کنترل شما هستند، URI Versioning ساده‌ترین و واضح‌ترین گزینه است. برای APIهای عمومی که برای توسعه‌دهندگان خارجی طراحی می‌شوند، Header Versioning تمیزتر است ولی نیاز به مستندسازی دقیق دارد.

سه نکته‌ی عملی در نسخه‌بندی که در پروژه‌های واقعی به آن‌ها رسیده‌ام:

• نسخه‌بندی را از روز اول شروع کنید: حتی اگر نسخه‌ی ۱ برایتان «شروع» است، مسیر را /api/v1/... بگذارید. اضافه‌کردن v1 بعداً، یک تغییر شکستنی برای همه‌ی کلاینت‌ها است.
• شکستن تغییرات را فقط در نسخه‌ی جدید انجام دهید: اگر می‌خواهید ساختار پاسخ را تغییر دهید، نسخه‌ی جدید بسازید. کلاینت قدیمی باید بتواند بدون تغییر به کار خود ادامه دهد.
• سیاست deprecation را از ابتدا اعلام کنید: هر نسخه چقدر زنده می‌ماند؟ چه زمانی از رده خارج می‌شود؟ این سیاست، هم برای تیم شما و هم برای مصرف‌کننده‌ها، چارچوب مشخصی می‌سازد.

مستندسازی خودکار

مستندسازی API، تفاوت بین یک API که مصرف‌کننده‌ها راحت استفاده می‌کنند و یکی که هر بار باید از توسعه‌دهنده‌ی اصلی بپرسند. FastAPI با OpenAPI و Swagger UI، این کار را خودکار می‌کند:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(
    title="My API",
    version="1.0.0",
    description="API for managing posts",
)

class PostCreate(BaseModel):
    title: str
    body: str

@app.post("/api/v1/posts", status_code=201)
def create_post(post: PostCreate):
    """Create a new post."""
    return {"id": 1, **post.dict()}

با اجرا، مستندات به‌طور خودکار در /docs قابل دسترسی است. این ویژگی، در پروژه‌های واقعی، ساعت‌ها کار مستندسازی دستی را حذف می‌کند.

در Flask، ابزارهایی مثل flask-smorest و flask-restx همین کار را انجام می‌دهند، ولی به‌اندازه‌ی FastAPI یکپارچه نیستند. اگر مستندسازی خودکار برایتان مهم است، این یکی از دلایلی است که FastAPI را جدی بگیرید.

تست API پیش از انتشار

یک API بدون تست، مثل یک ماشین بدون ترمز اضطراری است. سه سطح تست که در پروژه‌های واقعی به‌کار می‌برم:

۱) تست واحد با pytest

from fastapi.testclient import TestClient
from app import app

client = TestClient(app)

def test_health_check():
    response = client.get("/api/health")
    assert response.status_code == 200
    assert response.json()["status"] == "ok"

def test_create_post_with_invalid_data():
    response = client.post("/api/v1/posts", json={})
    assert response.status_code == 422

۲) تست دستی با Postman

روش ساخت، تست و مستندسازی API با Postman در تست REST API با Postman با جزئیات آمده. نکته‌ی مهم: collectionهای Postman را در مخزن نگه دارید تا اعضای تیم از همان تست‌ها استفاده کنند.

۳) تست بار با locust یا k6

قبل از انتشار در محیط تولید، API را تحت بار تست کنید. یک API که در تست تک‌کاربره سریع است، ممکن است در ۱۰۰ کاربر همزمان سقوط کند. برای راهنمای بهینه‌سازی، بهینه‌سازی عملکرد REST API نکات فنی مفیدی دارد.

استقرار در محیط تولید

سرور توسعه‌ی Flask و FastAPI، برای تولید ساخته نشده. ترکیب استاندارد در پروژه‌های واقعی:

pip install gunicorn

gunicorn -w 4 -b 127.0.0.1:8000 app:app

برای FastAPI که async است، از workerهای async استفاده کنید:

pip install "uvicorn[standard]" gunicorn

gunicorn app:app -w 4 -k uvicorn.workers.UvicornWorker -b 127.0.0.1:8000

سپس Nginx به‌عنوان reverse proxy، درخواست‌های کاربر را به workerها هدایت می‌کند. سه نکته‌ی مهم در استقرار که در پروژه‌های واقعی به آن‌ها رسیده‌ام:

• متغیرهای محیطی برای تنظیمات حساس: SECRET_KEY، DATABASE_URL و دیگر مقادیر حساس از محیط خوانده شوند، نه از کد.
• لاگ متمرکز: لاگ‌های Gunicorn و اپلیکیشن را در یک مسیر مشخص جمع کنید. ابزارهایی مثل Sentry یا ELK، در پروژه‌های جدی ارزششان را نشان می‌دهند.
• health check: یک endpoint سبک مثل /api/health برای ابزارهای monitoring که تأیید کند سرویس زنده است.
• محدودیت نرخ درخواست: برای جلوگیری از سوءاستفاده و حمله، از ابزارهایی مثل Flask-Limiter یا محدودیت Nginx استفاده کنید. این موضوع را در امنیت API و حمله DDoS چیست و چگونه دفع می‌شود باز کرده‌ام.

اشتباهاتی که در پروژه‌های واقعی دیده‌ام

در بازبینی APIهای پایتونی، این اشتباهات را زیاد دیده‌ام:

• نبود نسخه‌بندی از روز اول: بزرگ‌ترین اشتباهی که خودم هم مرتکب شدم. اضافه‌کردن v1 به مسیرها در ماه ششم، یک تغییر شکستنی است.
• اعتماد به داده‌ی ورودی: نبود Pydantic یا اعتبارسنجی دستی، باعث می‌شود داده‌های نامعتبر به دیتابیس بروند و بعداً به باگ‌های عجیب تبدیل شوند.
• بازگرداندن 200 برای همه‌چیز: خیلی از APIها همیشه 200 برمی‌گردانند و در بدنه، فیلد success: false می‌گذارند. این رویکرد، ابزارهای کلاینت و middleware را از کار می‌اندازد. از کد وضعیت HTTP درست استفاده کنید.
• نبود مستندسازی: API بدون مستندات، عملاً فقط برای نویسنده‌اش قابل استفاده است. حتی یک فایل OpenAPI پایه، تفاوت بزرگی می‌سازد.
• خطاهای مبهم: پیام "Something went wrong" برای همه‌ی خطاها. در پروژه‌های واقعی، مصرف‌کننده باید دقیقاً بداند چه چیزی اشتباه بوده تا بتواند خودش مشکل را حل کند.
• نبود rate limiting: بدون محدودیت نرخ، یک اسکریپت مخرب می‌تواند سرویس شما را از کار بیندازد.
• مصرف حافظه در queryهای بزرگ: برگرداندن هزاران رکورد در یک پاسخ، هم سرور را تحت فشار می‌گذارد و هم کلاینت را. همیشه pagination اضافه کنید.
• نبود CORS صحیح: اگر API شما از مرورگر مصرف می‌شود، تنظیم CORS را جدی بگیرید. استفاده از * در محیط تولید، یک خطر امنیتی است.
• اتکا به DEBUG=True در تولید: همان اشتباه کلاسیک. در Flask و Django، این تنظیم می‌تواند اطلاعات حساس فاش کند.
• نبود backup استراتژی: قبل از هر تغییر ساختاری، نسخه‌ی جدید API را در محیط staging تست کنید، نه روی production.

یک توصیه‌ی عملی از تجربه: قبل از انتشار API، سه سؤال از خودتان بپرسید: آیا نسخه‌بندی دارد؟ آیا مستندات خودکار یا دستی دارد؟ اگر یک مصرف‌کننده‌ی جدید بخواهد بدون صحبت با شما از آن استفاده کند، می‌تواند؟ اگر جواب هر سه سؤال «بله» است، API شما آماده‌ی تولید است. اگر حتی یکی «نه» است، یک sprint دیگر روی همان کار کنید. اشتباهات رایج در طراحی REST API که در اشتباهات رایج در REST API فهرست کرده‌ام، مکمل همین فهرست است.

سخن آخر

ساخت API با پایتون، از یک endpoint ساده شروع می‌شود ولی در پروژه‌های واقعی، به یک طراحی چندلایه تبدیل می‌شود: انتخاب چارچوب، اعتبارسنجی، احراز هویت، نسخه‌بندی، مستندسازی و استقرار. سه نکته‌ی مهم که در این مقاله به آن‌ها رسیدیم: اول، انتخاب چارچوب باید بر اساس اندازه و ماهیت پروژه باشد، نه محبوبیت روز بازار — Flask، FastAPI و DRF هرکدام جای خودشان را دارند؛ دوم، نسخه‌بندی و مستندسازی از روز اول — نه در ماه ششم که هر تغییر به یک بحران تبدیل می‌شود؛ سوم، اعتبارسنجی ورودی و کد وضعیت HTTP، ابزارهای اصلی شما برای ساختن APIای هستند که مصرف‌کننده‌هایش به آن اعتماد می‌کنند.

اگر امروز می‌خواهید شروع کنید، سه کار کوچک پیشنهاد می‌کنم: یک API کوچک با Flask یا FastAPI بسازید که یک لیست از داده را برمی‌گرداند، با Pydantic اعتبارسنجی کنید، و در پایان با یک فایل OpenAPI ساده مستندسازی کنید. همین پروژه‌ی کوچک، ۹۰٪ مفاهیم این مقاله را زنده می‌کند. اگر تجربه‌ای از ساخت API در پروژه‌های خودتان دارید — مخصوصاً اگر با چالش نسخه‌بندی، احراز هویت یا کارایی روبرو شده‌اید — در دیدگاه‌ها بنویسید؛ همین نکته‌های میدانی، برای خواننده‌ی بعدی از هر مستند رسمی ارزشمندتر است. 🔌