بتل کد Battle Codeدارد باز می‌شود…

جلسه‌ی 29: نقشه‌ی API: قبل از کد Planning an API

برنامه‌نویس‌های حرفه‌ای قبل از نوشتن حتی یک خط کد، نقشه‌ی API را می‌کشند: یک جدول از همه‌ی مسیرها، متدها و کد وضعیت هر حالت. نسخه را در آدرس می‌گذاری (/api/v1/...)، با @app.after به همه‌ی جواب‌ها یک هدر اضافه می‌کنی و با show_routes() می‌بینی کدت با نقشه یکی است یا نه.

در این جلسه یاد می‌گیری

درس

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

یادت هست؟ در جلسه‌ی ۲۷ دیدیم اگر یک مسیر وسط کار خراب شود و app.debug = False باشد، سرور به‌جای نشان دادن خطای پایتون فقط یک 500 ساده می‌دهد: {"error": "something went wrong on the server"}. جزئیات خطا هم به‌جای رفتن برای کاربر، در لیست app.logs نوشته می‌شود تا فقط خودت ببینی. در این برنامه لیست امتیازها خالی است و تقسیم بر صفر می‌شود.

from server import app, ask

app.debug = False

@app.get("/average")
def average():
    scores = []
    return {"average": sum(scores) / len(scores)}

ask("GET /average")
print(app.logs)

🗺️ اول نقشه، بعد کد. معمار قبل از ساختن خانه نقشه می‌کشد. تو هم قبل از نوشتن سرور یک جدول مسیرها (endpoint table) بکش: هر ردیف یک متد و یک مسیر، کاری که می‌کند، و کد وضعیت هر حالت، چه خوب چه بد. این نقشه‌ی یک API برای کتاب‌های کلاس است:

| متد | مسیر | کار | خوب | بد |
|---|---|---|---|---|
| GET | /api/v1/books | همه‌ی کتاب‌ها | 200 | |
| GET | /api/v1/books/<int:book_id> | یک کتاب | 200 | 404 نیست |
| POST | /api/v1/books | کتاب تازه | 201 | 400 عنوان ندارد، 409 تکراری |
| DELETE | /api/v1/books/<int:book_id> | پاک کردن | 204 | 404 نیست |

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

🔢 نسخه در آدرس: /api/v1/.... وقتی اپ کوییز روی گوشی صدها نفر نصب شد، دیگر نمی‌توانی شکل جواب‌ها را یک‌شبه عوض کنی: اپ‌های قدیمی خراب می‌شوند. برای همین آدرس‌ها با /api (که از صفحه‌های معمولی سایت جدا باشند) و شماره‌ی نسخه شروع می‌شوند. اگر روزی شکل جواب عوض شد، /api/v2/... می‌سازی و v1 را برای اپ‌های قدیمی نگه می‌داری. هر دو با هم کار می‌کنند.

from server import app, ask

@app.get("/api/v1/hello")
def hello_v1():
    return {"msg": "Hello"}

@app.get("/api/v2/hello")
def hello_v2():
    return {"message": "Hello", "lang": "en"}

ask("GET /api/v1/hello")
ask("GET /api/v2/hello")
ask("GET /hello")

✅ هر حالت، کد خودش. وقتی نقشه کد وضعیت هر حالت را گفته، کد فقط آن را پیاده می‌کند: هر جا حالت بد است، abort(...) با همان کد و یک پیام روشن. همه‌ی خطاها هم یک شکل دارند، {"error": "..."}، تا اپ همیشه بداند پیام خطا کجاست (جلسه‌ی ۱۰). ترتیب بررسی‌ها هم مهم است: اول «عنوان دارد؟» (400)، بعد «تکراری است؟» (409)، آخر ساختن (201).

from server import app, ask, request, abort

books = [{"id": 1, "title": "Wonder"}, {"id": 2, "title": "Matilda"}]

@app.post("/api/v1/books")
def add_book():
    data = request.json or {}
    title = data.get("title")
    if not title:
        abort(400, "title is required")
    for b in books:
        if b["title"] == title:
            abort(409, "this book is already here")
    book = {"id": len(books) + 1, "title": title}
    books.append(book)
    return book, 201

ask("POST /api/v1/books", {"title": "Coraline"})
ask("POST /api/v1/books", {"title": "Wonder"})
ask("POST /api/v1/books", {})

🏷️ @app.after: یک کار برای همه‌ی جواب‌ها. @app.before را از جلسه‌ی ۲۳ می‌شناسی: پیش از هر مسیر اجرا می‌شود. @app.after برعکس است: بعد از هر جواب اجرا می‌شود و خود جواب (response) را می‌گیرد. می‌تواند هدرهایش را عوض کند: response.headers["X-Version"] = "1". هدر (header) یک برچسب کنار جواب است که در بدنه نیست؛ مثل Authorization که در جلسه‌ی ۲۲ کنار درخواست می‌فرستادیم. این تابع برای همه‌ی جواب‌ها اجرا می‌شود، حتی 404ها، پس لازم نیست در هر مسیر تکرارش کنی. ask هدرها را چاپ نمی‌کند؛ با r.headers["X-Version"] بخوانشان.

from server import app, ask

@app.get("/api/v1/ping")
def ping():
    return {"pong": True}

@app.after
def add_version(response):
    response.headers["X-Version"] = "1"

r = ask("GET /api/v1/ping")
print("X-Version:", r.headers["X-Version"])
r = ask("GET /api/v1/nothing", quiet=True)
print(r.status, r.headers["X-Version"])

📖 app.show_routes(): راهنمای خودکار. این دستور همه‌ی مسیرهای سرورت را چاپ می‌کند: متد، مسیر، و تابعی که جواب می‌دهد، مرتب بر اساس مسیر. آن را کنار جدول نقشه بگذار: اگر ردیفی از نقشه این‌جا نیست، یعنی مسیری را جا انداخته‌ای؛ اگر چیزی این‌جاست که در نقشه نیست، یا نقشه را به‌روز کن یا مسیر را پاک کن. برای هم‌گروهی‌ات هم یک راهنمای (documentation) کوتاه و همیشه درست است.

from server import app

@app.get("/api/v1/books")
def all_books():
    return []

@app.post("/api/v1/books")
def add_book():
    return {}, 201

@app.get("/api/v1/books/<int:book_id>")
def one_book(book_id):
    return {}

app.show_routes()

⚠️ اشتباه‌های رایج:
- یک مسیر بدون نسخه جا می‌ماند (/books به‌جای /api/v1/books) و اپ 404 no route می‌گیرد. show_routes() این را زود نشان می‌دهد.
- فعل در آدرس: /api/v1/getBooks یا /api/v1/deleteBook/3. کار را متد می‌گوید، آدرس فقط اسم چیزهاست.
- خطاهایی با شکل‌های مختلف: یکی {"error": ...}، یکی {"msg": ...}، یکی فقط متن.
- تابع @app.after بدون پارامتر (def add_version():)؛ باید جواب را بگیرد: def add_version(response):.
- نوشتن کد بدون نقشه و بعد فهمیدن اینکه حالت‌های بد (400، 404، 409) فراموش شده‌اند.

مثال‌های این جلسه

چالش‌ها

  1. A Quiet Crash (آسان)
  2. Fill In the Plan (آسان)
  3. Version One (متوسط)
  4. A Label on Every Answer (متوسط)
  5. POST by the Plan (سخت)
  6. The Whole Plan (سخت)

بیشتر بخوان

← جلسه‌ی 28: پروژه: قفل کردن یک API جلسه‌ی 30: تست کردن سرور →