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

جلسه‌ی 13: POST: ساختن چیز تازه POST: Making New Things

تا حالا سرورت فقط جواب می‌داد؛ حالا چیز تازه می‌گیرد. کلاینت با POST یک بدنه‌ی JSON می‌فرستد (ask("POST /notes", {"text": "..."}))، سرور آن را با request.json می‌خواند، به چیز تازه یک شماره (id) می‌دهد، در لیست نگهش می‌دارد و با return note, 201 می‌گوید «ساخته شد».

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

درس

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

یادت هست؟ در فاز ۳ یاد گرفتی که اگر مسیر یک dict یا لیست برگرداند، سرور آن را JSON می‌فرستد، و یک API خوب لیست را به شکل {"count": n, "items": [...]} می‌دهد. سمت کلاینت هم با quiet=True چیزی چاپ نمی‌شود و جواب را از r.json می‌خوانی. این‌جا یک لیست یادداشت داریم که فقط خوانده می‌شود. امروز یاد می‌گیریم چیز تازه به آن اضافه کنیم.

from server import app, ask

notes = [
    {"id": 1, "text": "Buy milk"},
    {"id": 2, "text": "Call Ali"},
]

@app.get("/notes")
def all_notes():
    return {"count": len(notes), "items": notes}

r = ask("GET /notes", quiet=True)
print(r.status, r.json["count"])
for note in r.json["items"]:
    print(note["id"], note["text"])

با GET چیزی را می‌خوانی. برای فرستادن چیز تازه، روش POST است. درخواست POST یک بدنه (body) هم دارد: داده‌ای که کلاینت همراهش می‌فرستد. در ask بدنه را بعد از آدرس به شکل یک dict بنویس: ask("POST /hello", {"name": "Sara"})؛ این dict به شکل JSON فرستاده می‌شود. سمت سرور، مسیر را با @app.post(...) بساز و بدنه را با request.json بخوان: یک dict مثل همان که فرستاده شد. (request را هم مثل جلسه‌ی ۶ از server بیاور.)

from server import app, ask, request

@app.post("/hello")
def hello():
    data = request.json
    return {"message": "Hello, " + data["name"] + "!"}

ask("POST /hello", {"name": "Sara"})
ask("POST /hello", {"name": "Reza"})

حالا چیز تازه را نگه داریم. یک لیست خالی notes = [] بیرون از تابع می‌سازیم تا بین درخواست‌ها بماند. هر یادداشت تازه یک شماره (id) لازم دارد که با بقیه فرق کند. ساده‌ترین راه: «یکی بیشتر از تعداد فعلی»، یعنی len(notes) + 1. بعد با notes.append(note) آن را به لیست اضافه می‌کنیم و خود یادداشت را برمی‌گردانیم. (یادت باشد: سرور این دوره در حافظه است و با هر اجرا از صفر شروع می‌شود؛ در فاز ۵ پایگاه داده می‌آید.)

from server import app, ask, request

notes = []

@app.post("/notes")
def add_note():
    data = request.json
    note = {"id": len(notes) + 1, "text": data["text"]}
    notes.append(note)
    return note

ask("POST /notes", {"text": "Buy milk"})
ask("POST /notes", {"text": "Call Ali"})
print(len(notes), "notes in the list")

جواب بالا 200 OK بود. ولی وقتی چیزی ساخته می‌شود، کد درستش 201 Created است. پس بنویس return note, 201 (یادت هست؟ از جلسه‌ی ۳ می‌شود کد وضعیت را بعد از بدنه نوشت). چرا خود یادداشت را برمی‌گردانیم؟ چون کلاینت شماره‌اش را نمی‌داند؛ این شماره را سرور ساخته. کلاینت آن را از r.json["id"] برمی‌دارد تا بعداً بتواند همین یادداشت را بخواهد.

from server import app, ask, request

notes = []

@app.post("/notes")
def add_note():
    data = request.json
    note = {"id": len(notes) + 1, "text": data["text"]}
    notes.append(note)
    return note, 201

ask("POST /notes", {"text": "Buy milk"})
r = ask("POST /notes", {"text": "Call Ali"}, quiet=True)
print("new id:", r.json["id"], "status:", r.status)

در جلسه‌ی ۱۰ دیدی که فعل در روش است، نه در آدرس. پس برای «همه‌ی یادداشت‌ها را بده» و «یک یادداشت بساز» یک آدرس داریم: /notes. GET /notes می‌خواند و POST /notes می‌سازد. دو تابع جدا با دو برچسب: @app.get("/notes") و @app.post("/notes"). آدرس‌هایی مثل /addNote یا /notes/new لازم نیست. app.show_routes() هر دو را نشان می‌دهد. در Flask واقعی هم همین شکل است:
``python
@app.post("/notes")
def add_note():
data = request.json
...
return note, 201
``

from server import app, ask, request

notes = []

@app.get("/notes")
def all_notes():
    return {"count": len(notes), "items": notes}

@app.post("/notes")
def add_note():
    note = {"id": len(notes) + 1, "text": request.json["text"]}
    notes.append(note)
    return note, 201

ask("GET /notes")
ask("POST /notes", {"text": "Buy milk"})
ask("POST /notes", {"text": "Call Ali"})
ask("GET /notes")
app.show_routes()

اشتباه‌های رایج:
- لیست را داخل تابع ساختن: notes = [] داخل add_note با هر درخواست یک لیست خالی تازه می‌سازد. همه‌ی یادداشت‌ها شماره‌ی ۱ می‌گیرند و هیچ‌کدام نمی‌ماند. کد زیر را اجرا کن و ببین.
- خواندن بدنه با request.args: آن فقط تکه‌ی ?... آدرس است. بدنه در request.json است.
- جا انداختن 201: کار می‌کند ولی کلاینت 200 می‌گیرد و نمی‌فهمد چیزی ساخته شد.
- @app.get به‌جای @app.post: آن‌وقت POST جواب 405 می‌گیرد.

from server import app, ask, request

@app.post("/notes")
def add_note():
    notes = []
    note = {"id": len(notes) + 1, "text": request.json["text"]}
    notes.append(note)
    return note, 201

ask("POST /notes", {"text": "Buy milk"})
ask("POST /notes", {"text": "Call Ali"})

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

چالش‌ها

  1. The Score List (آسان)
  2. Greet Me (آسان)
  3. New Books (متوسط)
  4. Which Number? (متوسط)
  5. Sign Up the Team (سخت)
  6. Fix the Message Box (سخت)

بیشتر بخوان

← جلسه‌ی 12: پروژه: API آمار بازی و کلاینتش جلسه‌ی 14: PUT، PATCH و DELETE →