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

جلسه‌ی 18: API روی SQL An API on Top of SQL

API فاز ۴ را روی پایگاه داده می‌گذاری. ردیف‌هایی که db.all و db.one می‌دهند دیکشنری‌اند، پس مستقیم برشان می‌گردانی و JSON می‌شوند. اگر db.one چیزی پیدا نکرد None می‌دهد و تو 404 می‌دهی؛ ?kind= به WHERE تبدیل می‌شود؛ و POST یک ردیف INSERT می‌کند و با .id ردیف تازه را با 201 برمی‌گرداند.

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

درس

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

یادت هست؟ در جلسه‌ی ۱۷ دیدیم db.all(...) لیستی از دیکشنری‌ها می‌دهد (هر ردیف یک دیکشنری)، db.one(...) یک دیکشنری یا None، و db.value(...) یک مقدار تنها. مقدارها همیشه با ? جدا داده می‌شوند.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE pets (id INTEGER PRIMARY KEY, name TEXT, kind TEXT, age INTEGER);
INSERT INTO pets (name, kind, age) VALUES ('Pishi', 'cat', 3);
INSERT INTO pets (name, kind, age) VALUES ('Max', 'dog', 5);
INSERT INTO pets (name, kind, age) VALUES ('Coco', 'bird', 1);
INSERT INTO pets (name, kind, age) VALUES ('Luna', 'cat', 2);
''')

print(db.all("SELECT name, kind FROM pets WHERE age < ?", (3,)))
print(db.one("SELECT name FROM pets WHERE id = ?", 1))
print(db.one("SELECT name FROM pets WHERE id = ?", 7))
print(db.value("SELECT COUNT(*) FROM pets"))

ردیف‌ها دیکشنری‌اند، پس برشان گردان. در فاز ۳ دیدیم اگر یک مسیر دیکشنری یا لیست برگرداند، سرور آن را JSON می‌فرستد. db.all درست همین را می‌دهد: لیستی از دیکشنری‌ها. پس return db.all(...) کافی است. کلیدهای JSON به همان ترتیب ستون‌های SELECT می‌آیند؛ اگر فقط چند ستون می‌خواهی، فقط همان‌ها را SELECT کن.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE pets (id INTEGER PRIMARY KEY, name TEXT, kind TEXT, age INTEGER);
INSERT INTO pets (name, kind, age) VALUES ('Pishi', 'cat', 3);
INSERT INTO pets (name, kind, age) VALUES ('Max', 'dog', 5);
INSERT INTO pets (name, kind, age) VALUES ('Coco', 'bird', 1);
INSERT INTO pets (name, kind, age) VALUES ('Luna', 'cat', 2);
''')

@app.get("/pets")
def all_pets():
    return db.all("SELECT id, name, kind FROM pets ORDER BY id")

ask("GET /pets")

یک ردیف، یا 404. برای GET /pets/<int:pet_id> از db.one("... WHERE id = ?", (pet_id,)) استفاده کن. اگر ردیفی با آن شماره نباشد، db.one جواب None می‌دهد. آن وقت abort(404, "...")؛ وگرنه خود ردیف را برگردان. مثل فاز ۲، فقط این بار به‌جای گشتن در یک لیست، پایگاه داده می‌گردد.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE pets (id INTEGER PRIMARY KEY, name TEXT, kind TEXT, age INTEGER);
INSERT INTO pets (name, kind, age) VALUES ('Pishi', 'cat', 3);
INSERT INTO pets (name, kind, age) VALUES ('Max', 'dog', 5);
INSERT INTO pets (name, kind, age) VALUES ('Coco', 'bird', 1);
INSERT INTO pets (name, kind, age) VALUES ('Luna', 'cat', 2);
''')

@app.get("/pets/<int:pet_id>")
def one_pet(pet_id):
    pet = db.one("SELECT * FROM pets WHERE id = ?", (pet_id,))
    if pet is None:
        abort(404, "no pet with id " + str(pet_id))
    return pet

ask("GET /pets/2")
ask("GET /pets/9")

فیلتر با ?kind=. مقدار request.args.get("kind") از آدرس می‌آید، یعنی از بیرون؛ پس با ? به WHERE بده، نه با چسباندن. اگر نیامده بود (None)، همه را برگردان. چون هر دو حالت یک شکل جواب دارند، می‌شود مثل فاز ۳ {"count": ..., "items": ...} برگرداند.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE pets (id INTEGER PRIMARY KEY, name TEXT, kind TEXT, age INTEGER);
INSERT INTO pets (name, kind, age) VALUES ('Pishi', 'cat', 3);
INSERT INTO pets (name, kind, age) VALUES ('Max', 'dog', 5);
INSERT INTO pets (name, kind, age) VALUES ('Coco', 'bird', 1);
INSERT INTO pets (name, kind, age) VALUES ('Luna', 'cat', 2);
''')

@app.get("/pets")
def find_pets():
    kind = request.args.get("kind")
    if kind:
        rows = db.all("SELECT name, kind FROM pets WHERE kind = ? ORDER BY name", (kind,))
    else:
        rows = db.all("SELECT name, kind FROM pets ORDER BY name")
    return {"count": len(rows), "items": rows}

ask("GET /pets?kind=cat")
ask("GET /pets")

POST یعنی INSERT. همان کار فاز ۴: request.json را بخوان و بررسی کن (400 اگر چیزی کم است). بعد به‌جای append، db.run("INSERT ...", (...)). شماره را دیگر خودمان حساب نمی‌کنیم: done.id شماره‌ای است که پایگاه داده داد. بعد ردیف تازه را با db.one بخوان و با 201 برگردان، تا مشتری ببیند دقیقاً چه ذخیره شد.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE pets (id INTEGER PRIMARY KEY, name TEXT, kind TEXT, age INTEGER);
INSERT INTO pets (name, kind, age) VALUES ('Pishi', 'cat', 3);
INSERT INTO pets (name, kind, age) VALUES ('Max', 'dog', 5);
INSERT INTO pets (name, kind, age) VALUES ('Coco', 'bird', 1);
INSERT INTO pets (name, kind, age) VALUES ('Luna', 'cat', 2);
''')

@app.post("/pets")
def add_pet():
    data = request.json
    if not data or not data.get("name"):
        abort(400, "name is required")
    done = db.run("INSERT INTO pets (name, kind, age) VALUES (?, ?, ?)", (data["name"], data.get("kind", "cat"), data.get("age", 0)))
    return db.one("SELECT * FROM pets WHERE id = ?", (done.id,)), 201

ask("POST /pets", {"name": "Simba", "kind": "cat", "age": 4})
ask("POST /pets", {"kind": "dog"})

اشتباه‌های رایج:
- None را بررسی نکردن: pet = db.one(...) و بعد pet["name"]. اگر ردیفی نباشد، خطای 'NoneType' object is not subscriptable می‌گیری. اول if pet is None:.
- CREATE TABLE را داخل مسیر گذاشتن: درخواست دوم با table pets already exists می‌شکند. جدول‌ها یک بار، بالای برنامه.
- فراموش کردن 201 برای چیز تازه: return pet یعنی 200.
- چسباندن چیزی که از درخواست آمده (request.args، request.json) به متن SQL. همیشه ?.

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

چالش‌ها

  1. Nobody Home (آسان)
  2. List the Pets (آسان)
  3. One Pet or 404 (متوسط)
  4. Only the Cats (متوسط)
  5. A New Pet (سخت)
  6. No Book Twice (سخت)

بیشتر بخوان

← جلسه‌ی 17: حافظه فراموش می‌کند: پایگاه داده جلسه‌ی 19: عوض کردن ردیف‌ها و صفحه‌بندی →