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

جلسه‌ی 10: طراحی یک API خوب Designing a Good API

یک API خوب مثل یک منوی خوب است: حدس زدنش آسان است. آدرس‌ها اسم چیزها هستند و جمع (/books، /books/3)، و کار را متد می‌گوید نه آدرس. خطاها همیشه یک شکل دارند ({"error": ...} با کد وضعیت درست)، فهرست‌ها در یک «پاکت» می‌آیند ({"count": n, "items": [...]}) و app.show_routes() نقشه‌ی همه‌ی routeها را چاپ می‌کند.

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

درس

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

یادت هست؟ در جلسه‌ی ۹ دیدیم وقتی route دیکشنری یا لیست برمی‌گرداند، سرور آن را به متن JSON تبدیل می‌کند: True می‌شود true و None می‌شود null. در سمت مشتری هم r.text همان متن است و r.json دیکشنری آماده که می‌شود تودرتو خواندش: r.json["items"][0]["name"].

from server import app, ask

@app.get("/shop")
def shop():
    return {"open": True, "owner": None, "items": [{"name": "pen", "price": 2}]}

r = ask("GET /shop", quiet=True)
print(r.text)
print(r.json["items"][0]["name"])

در جلسه‌ی ۱ گفتیم API مثل منوی رستوران است. منوی خوب را بدون توضیح می‌شود فهمید. قانون ۱: آدرس اسم یک چیز است و جمع: /books همه‌ی کتاب‌ها، /books/3 کتاب شماره‌ی ۳، /books/3/reviews نظرهای همان کتاب. قانون ۲: کار را متد می‌گوید، نه آدرس. GET می‌خواند؛ بعدها POST اضافه می‌کند و DELETE پاک می‌کند، روی همان آدرس. پس /getBooks، /book/all و /deleteBook?id=3 آدرس‌های بدی‌اند. ببین: DELETE /books/3 اینجا 405 می‌گیرد، چون فعلاً فقط GET داریم.

from server import app, ask, abort

books = [
    {"id": 1, "title": "The Hobbit", "genre": "fantasy"},
    {"id": 2, "title": "Wonder", "genre": "story"},
    {"id": 3, "title": "Coraline", "genre": "fantasy"},
]

@app.get("/books/<int:book_id>")
def one_book(book_id):
    for book in books:
        if book["id"] == book_id:
            return book
    abort(404, f"no book with id {book_id}")

ask("GET /books/3")
ask("DELETE /books/3")

خطاها یک شکل دارند. هر خطا یک دیکشنری با کلید error است و کد وضعیت درست: {"error": "no book with id 9"} با 404، یا {"error": "add ?q=..."} با 400. abort(404, "...") خودش همین شکل را می‌سازد؛ اگر خودت برمی‌گردانی، بنویس return {"error": "..."}, 400. حتی 404 خودِ سرور برای آدرسی که نیست همین شکل را دارد. این‌طوری مشتری همیشه می‌داند خطا کجاست: r.json["error"]. پیام را کوتاه و روشن بنویس و اگر می‌شود بگو چه کار کند.

from server import app, ask, request

@app.get("/search")
def search():
    q = request.args.get("q")
    if not q:
        return {"error": "add ?q=... (for example ?q=hobbit)"}, 400
    return {"q": q, "count": 0, "items": []}

ask("GET /search")
ask("GET /serch?q=hobbit")
r = ask("GET /search", quiet=True)
print(r.status, r.json["error"])

فهرست‌ها در پاکت. به‌جای یک لیست خالی و تنها، فهرست را در یک دیکشنری بگذار: {"count": 2, "items": [...]}. سه دلیل: مشتری بدون شمردن می‌داند چند تا آمده؛ «هیچی» هم روشن است ({"count": 0, "items": []})؛ و بعدها می‌شود چیزهای تازه کنارش گذاشت (مثل "page": 2) بی‌آنکه برنامه‌ی مشتری‌ها خراب شود. یک لیست تنها جایی برای این چیزها ندارد.

from server import app, ask, request

books = [
    {"id": 1, "title": "The Hobbit", "genre": "fantasy"},
    {"id": 2, "title": "Wonder", "genre": "story"},
    {"id": 3, "title": "Coraline", "genre": "fantasy"},
]

@app.get("/books")
def all_books():
    genre = request.args.get("genre")
    items = []
    for book in books:
        if not genre or book["genre"] == genre:
            items.append(book)
    return {"count": len(items), "items": items}

ask("GET /books?genre=fantasy")
ask("GET /books?genre=poetry")

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

from server import app

@app.get("/books")
def all_books():
    return {"count": 0, "items": []}

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

@app.get("/books/<int:book_id>/reviews")
def book_reviews(book_id):
    return {"count": 0, "items": []}

app.show_routes()

اشتباه‌های رایج:
- فعل در آدرس: /getBooks یا /books/delete/3. کار را متد بگوید.
- خطا با 200: return {"error": "no such book"} بدون 404. مشتری r.ok را True می‌بیند و فکر می‌کند همه‌چیز خوب است!
- شکل‌های مختلف: یک جا {"error": ...}، یک جا {"message": ...}، یک جا متن Not found!. مشتری گیج می‌شود.
- اسم‌های قاطی: یک جا /book/3، یک جا /books. همیشه جمع.

from server import app, ask

@app.get("/books/<int:book_id>")
def one_book(book_id):
    return {"error": "no such book"}

r = ask("GET /books/9")
print("ok?", r.ok)

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

چالش‌ها

  1. The Door (آسان)
  2. Good Addresses (آسان)
  3. An Honest 404 (متوسط)
  4. Players in an Envelope (متوسط)
  5. The Games API (سخت)
  6. Fix a Messy API (سخت)

بیشتر بخوان

← جلسه‌ی 9: JSON: زبان APIها جلسه‌ی 11: سمت مشتری: استفاده از API →