درخواست و پاسخ HTTP از دید سازنده ورک‌فلو

اجزای یک درخواست و پاسخ HTTP را بشناس، درخواست واقعی به یک API آزمایشی بفرست و از روی کد وضعیت بفهمی چه شد.

بعد از این درس می‌توانی

  • اجزای درخواست HTTP (روش، نشانی، هدر، بدنه) و پاسخ (کد وضعیت، هدر، بدنه) را در یک نمونه واقعی نام ببرد.
  • روش مناسب (GET، POST، PUT، PATCH، DELETE) را برای یک کار انتخاب کند و بگوید تکرار کدام‌یک اثر دوباره دارد.
  • از روی کلاس کد وضعیت (2xx، 4xx، 5xx) تشخیص بدهد مشکل از درخواست است یا از سرور.
  • با یک کلاینت HTTP یا curl درخواست GET و POST به API آزمایشی بفرستد و پاسخ را بخواند.

چرا این درس مهم است

طرح «سفارشم کجاست؟» در دوره قبل یک گام ساده داشت: «خواندن وضعیت سفارش از سامانه». روی کاغذ یک خط است؛ در عمل یعنی ورک‌فلو باید از سامانه سفارش بپرسد و جواب را بفهمد. اگر جواب «404» باشد، یعنی سفارش نیست یا نشانی غلط است؟ اگر «401» باشد، کلید منقضی شده؟ اگر «503» باشد، باید دوباره امتحان کرد؟

تقریباً همه ابزارهایی که در این مسیر به هم وصل می‌کنی، از n8n تا API مدل‌های زبانی، با همین زبان حرف می‌زنند: HTTP. کسی که آن را بفهمد، خطای ورک‌فلو را در یک دقیقه می‌خواند؛ کسی که نفهمد، ساعت‌ها گره‌ها را جابه‌جا می‌کند. این درس آن زبان را با یک API آزمایشی روی کامپیوتر خودت تمرین می‌کند.

مفاهیم کلیدی

یادآوری: API را در دوره پایه دیدی: راهی برای اینکه یک برنامه از برنامه دیگر کاری بخواهد.

  • HTTP Request (درخواست HTTP): پیامی که کلاینت می‌فرستد: روش، نشانی، هدرها و گاهی بدنه.
  • HTTP Response (پاسخ HTTP): پیامی که سرور برمی‌گرداند: کد وضعیت، هدرها و معمولاً بدنه.
  • HTTP Method (روش HTTP): فعلی که هدف درخواست را می‌گوید؛ مثل GET برای خواندن و POST برای ساختن.
  • Status Code (کد وضعیت): عدد سه‌رقمی که نتیجه درخواست را می‌گوید؛ رقم اول کلاسش را.
  • HTTP Header (هدر): جفت نام و مقدار که اطلاعات جانبی درباره پیام می‌دهد؛ مثل نوع محتوا یا کلید دسترسی.
  • Endpoint (نقطه پایانی): نشانی مشخصی از یک API که یک کار مشخص انجام می‌دهد؛ مثل /orders/BS-1001.
  • Idempotent (ایدمپوتنت): روشی که اگر یک درخواست یکسان چند بار تکرار شود، اثرش روی سرور مثل یک بار است.

مدل ذهنی

HTTP را مثل فرم درخواست در باجه اداره ببین. روی فرم نوشته‌ای چه می‌خواهی (روش)، از کدام واحد (نشانی)، چند مشخصه بالای فرم (هدر: کیستی، زبان فرم) و گاهی پیوست (بدنه). باجه یک برگه جواب برمی‌گرداند با یک مهر (کد وضعیت) و شاید یک پیوست. مهر «فرم ناقص است» یعنی ایراد از توست؛ مهر «سامانه قطع است» یعنی ایراد از اداره.

رفت و برگشت یک درخواست HTTP: کلاینت درخواست GET با هدر احراز هویت به نقطه پایانی سفارش می‌فرستد؛ سرور پاسخ 200 با بدنه JSON برمی‌گرداند؛ در حالت دیگر سرور 404 با بدنه خطا برمی‌گرداند.

رفت و برگشت یک درخواست HTTP

این تشبیه کجا غلط است؟ باجه اداره ممکن است تو را بشناسد و پرونده‌ات را به خاطر بیاورد. HTTP بی‌حالت است: سرور بین دو درخواست چیزی از تو نگه نمی‌داردsrc-mdn-http، مگر اینکه با ابزارهای دیگر (مثل کوکی یا کلید در هر درخواست) این را بسازی. برای همین کلید دسترسی در هر درخواست فرستاده می‌شود، نه فقط بار اول.

گام‌به‌گام

گام ۱: اجزای درخواست

POST /tickets HTTP/1.1
Host: 127.0.0.1:8787
Authorization: Bearer local-demo-token
Content-Type: application/json

{"customer_ref": "C-01", "category": "order_shipping", "text": "سفارشم کجاست؟"}
  • خط اول: روش (POST) و مسیر (/tickets).
  • هدرها: Authorization می‌گوید کیستی؛ Content-Type می‌گوید بدنه چه قالبی دارد.
  • خط خالی، بعد بدنه: داده‌ای که می‌فرستی. درخواست GET معمولاً بدنه ندارد؛ پارامترهایش در نشانی می‌آید: /orders?page=2&limit=3.

گام ۲: روش‌ها و اثر تکرار

روشکار معمولتکرارش اثر دوباره دارد؟
GETخواندننه (فقط می‌خواند)
POSTساختن چیز تازهبله: دو بار، دو تیکت
PUTجایگزین کردن کاملنه
PATCHتغییر بخشی از یک چیزممکن است
DELETEحذفنه (بار دوم چیزی برای حذف نیست)

طبق تعریف MDN، روشی ایدمپوتنت است که اثر مورد نظرش روی سرور با یک بار یا چند بار تکرار یکسان باشد؛ GET، PUT و DELETE ایدمپوتنت‌اند و POST و PATCH نیستندsrc-mdn-idempotent. این تعریف درباره اثر روی سرور است، نه پاسخ: DELETE دوم ممکن است 404 بگیرد ولی اثرش همان است. اهمیت عملی: وقتی در درس چهارم خطا و تلاش دوباره را می‌سازی، تکرار POST خطرناک‌ترین حالت است.

گام ۳: کلاس کد وضعیت را بخوان

MDN کدهای وضعیت را در پنج کلاس دسته‌بندی می‌کند: اطلاعاتی، موفق، تغییر مسیر، خطای کلاینت و خطای سرورsrc-mdn-http. رقم اول کافی است تا بدانی دنبال چه بگردی:

کلاسیعنینمونه‌هایی که زیاد می‌بینیاول کجا را نگاه کن
2xxموفق200 OK، 201 Createdبدنه را بخوان
3xxجای دیگری برو301، 302نشانی تازه در هدر Location
4xxایراد در درخواست تو400 بدنه نامعتبر، 401 بدون کلید معتبر، 403 اجازه نداری، 404 پیدا نشد، 415 نوع محتوای اشتباه، 429 زیادی درخواست دادیدرخواست خودت را
5xxایراد در سرور500 خطای داخلی، 503 موقتاً در دسترس نیستصبر و تلاش دوباره (درس چهارم)

قاعده عملی: با 4xx، تکرار همان درخواست معمولاً همان نتیجه را می‌دهد (به‌جز 429)؛ درخواست را درست کن. با 5xx، شاید چند ثانیه بعد درست شود.

گام ۴: بدنه خطا را هم بخوان

کد وضعیت می‌گوید چه نوع مشکلی است؛ بدنه معمولاً می‌گوید دقیقاً چه. API آزمایشی برگ سبز برای 400 می‌نویسد کدام فیلد جا افتاده است. بسیاری از API‌ها یک شناسه درخواست هم در هدر برمی‌گردانند (در API آزمایشی: X-Request-Id) که برای پیگیری با پشتیبانی آن سرویس به کار می‌آید.

مثال‌ها

پیاده‌سازی عملی

اولین درخواست‌ها به API آزمایشی برگ سبز. حدود ۲۰ دقیقه. هدف: چهار درخواست بفرستی و برای هرکدام روش، کد وضعیت و معنی‌اش را در یک جدول کوچک بنویسی.

اجرای محلی

API آزمایشی (shared/barg-sabz-mock-api.py) فقط با Python و بدون نصب بسته اجرا می‌شود و فقط روی کامپیوتر خودت در دسترس است:

فایل را از فایل‌های درس بردار و در همان پوشه اجرا کن (در Windows اگر python شناخته نشد، py را امتحان کن):

python barg-sabz-mock-api.py

پیام «Barg Sabz mock API (synthetic data) on http://127.0.0.1:8787» یعنی آماده است. پنجره را باز بگذار و در پنجره دیگری درخواست‌ها را بفرست. کلید آزمایشی local-demo-token است؛ یک مقدار نمایشی، نه راز. راهنمای کامل نقطه‌های پایانی در shared/barg-sabz-mock-api.README.md است.

بدون اجرا / شبیه‌ساز

اگر نمی‌توانی چیزی اجرا کنی، assets/recorded-exchanges.md شش درخواست و پاسخ کاملشان را دارد. همان جدول را از روی آن پر کن و برای هر پاسخ بنویس اگر ورک‌فلو بودی، چه می‌کردی.

بدون کد

در کلاینت گرافیکی (یا گره HTTP Request در n8n) یک درخواست تازه بساز:

  1. GET http://127.0.0.1:8787/health بدون هیچ هدری. باید 200 بگیری.
  2. GET http://127.0.0.1:8787/orders/BS-1001 بدون هدر. باید 401 بگیری؛ بدنه را بخوان.
  3. همان را با هدر Authorization و مقدار Bearer local-demo-token دوباره بفرست. 200 و جزئیات سفارش.
  4. POST http://127.0.0.1:8787/tickets با هدر Authorization، نوع بدنه JSON و بدنه گام ۱. باید 201 و شناسه تیکت بگیری. یک بار دیگر بفرست: تیکت دوم ساخته می‌شود.
با کد

با curl (گزینه -i هدرهای پاسخ را هم نشان می‌دهد):

curl -i http://127.0.0.1:8787/health
curl -i http://127.0.0.1:8787/orders/BS-1001
curl -i -H "Authorization: Bearer local-demo-token" http://127.0.0.1:8787/orders/BS-1001
curl -i -H "Authorization: Bearer local-demo-token" \
     -H "Content-Type: application/json" \
     -d '{"customer_ref":"C-01","category":"order_shipping","text":"سفارشم کجاست؟"}' \
     http://127.0.0.1:8787/tickets

در Windows PowerShell به‌جای curl از curl.exe استفاده کن تا نسخه اصلی curl اجرا شود، و نقل‌قول‌های بدنه را مطابق PowerShell تنظیم کن یا بدنه را در فایل بگذار و با -d @body.json بفرست.

در پایان، یک بار هم GET /tickets بفرست و ببین دو تیکت تکراری ساخته شده است. این همان «اجرای تکراری» درس آخر دوره پایه است، این بار در سطح HTTP.

اشتباه‌های رایج

اشتباهنتیجهکار درست
فقط بدنه را نگاه کنی، نه کد وضعیتخطا را موفقیت فرض می‌کنیاول کد، بعد بدنه
404 را همیشه «وجود ندارد» بدانینشانی غلط را با «سفارش نیست» اشتباه می‌گیریمسیر و شناسه را هم بررسی کن
برای ساختن از GET استفاده کنی یا برای خواندن از POSTرفتار غیرمنتظره، کش‌شدن یا تکرار ناخواستهروش متناسب با کار
Content-Type را برای بدنه JSON نگذاری415 یا 400هدر نوع محتوا را همیشه بفرست
تکرار POST بدون فکردو تیکت، دو پرداختدرس چهارم: کلید جلوگیری از تکرار
کلید را فقط در درخواست اول بفرستی401 در درخواست‌های بعدیHTTP بی‌حالت است؛ هر درخواست کامل

اشکال‌زدایی

همه درخواست‌ها 401 می‌گیرند.

هدر Authorization نیست، املای Bearer غلط است، یا بعد از آن فاصله نیست.

درخواست فرستاده‌شده را کامل ببین (در curl با -v)؛ مقدار هدر را حرف‌به‌حرف با نمونه مقایسه کن.

Authorization: Bearer <کلید> با یک فاصله. اگر درست است، کلید منقضی یا لغو شده است.

POST با 400 و پیام invalid_json یا 415 برمی‌گردد.

بدنه JSON معتبر نیست (نقل‌قول یا ویرگول جاافتاده) یا Content-Type فرستاده نشده است.

بدنه را جداگانه در یک اعتبارسنج JSON بگذار؛ هدرهای فرستاده‌شده را ببین.

بدنه را درست کن و هدر Content-Type: application/json را اضافه کن.

curl می‌گوید «Connection refused» و هیچ کد وضعیتی نمی‌آید.

هیچ سروری روی آن نشانی و درگاه گوش نمی‌دهد؛ API آزمایشی اجرا نشده یا روی درگاه دیگری است.

این خطای شبکه است، نه HTTP؛ پنجره‌ای که API در آن اجراست را ببین.

API را اجرا کن یا درگاه را درست کن. در ورک‌فلو، این نوع خطا را جدا از 4xx و 5xx ثبت کن.

تمرین کوتاه

تمرین · 10 دقیقه

هدف: خواندن پاسخ و تصمیم.

گام‌ها: برای هر پاسخ بنویس کلاس، معنی و اینکه ورک‌فلو چه کند (ادامه، اصلاح درخواست، تلاش دوباره، توقف و هشدار).

  1. 201 Created با بدنه تیکت تازه.
  2. 400 با {"error": {"code": "validation_error", "message": "missing or non-string fields: text"}}
  3. 403 Forbidden
  4. 503 با temporarily_unavailable
  5. 404 برای نشانی /order/BS-1001 (بدون s)

معیار پذیرش: هر پنج مورد درست؛ مورد ۵ به‌عنوان نشانی غلط، نه «سفارش نیست».

راه‌حل نمونه

۱: موفق؛ ادامه و ثبت شناسه تیکت. ۲: خطای کلاینت؛ فیلد text را اضافه کن، تکرار بی‌فایده است. ۳: خطای کلاینت؛ کلید هست ولی اجازه ندارد؛ توقف و هشدار به مسئول دسترسی. ۴: خطای سرور؛ تلاش دوباره با فاصله، بعد صف انسانی. ۵: خطای کلاینت؛ مسیر غلط است (/orders درست است)؛ درخواست را اصلاح کن.

چالش

تمرین · 30 دقیقه

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

  1. برای هر اتصال، یک «کارت درخواست» بنویس: روش، نقطه پایانی، هدرها (بدون مقدار واقعی کلید)، بدنه نمونه و پاسخ موفق نمونه.
  2. برای هر کارت، سه پاسخ ناموفق محتمل (یک 4xx، یک 5xx، یک خطای شبکه) و رفتار ورک‌فلو برای هرکدام را بنویس.
  3. بگو کدام درخواست‌ها اثر تکراری دارند و اگر دو بار اجرا شوند چه می‌شود.

خروجی مورد انتظار: دست‌کم دو کارت درخواست با پاسخ موفق، سه پاسخ ناموفق و رفتار هرکدام، و علامت «اثر تکراری» برای هر درخواست.

معیار پذیرش:

  • روش هر درخواست با کارش جور است.
  • هیچ کلید یا داده واقعی در کارت‌ها نیست؛ نمونه‌ها ساختگی یا ناشناس‌اند.
  • رفتار 4xx «اصلاح یا توقف» است و رفتار 5xx «تلاش دوباره محدود»، نه برعکس.
  • درخواست‌های POST یا PATCH با اثر تکراری مشخص شده‌اند.

پرسش‌های سنجش

جمع‌بندی

  • درخواست HTTP روش، نشانی، هدر و گاهی بدنه دارد؛ پاسخ، کد وضعیت، هدر و بدنه.
  • HTTP بی‌حالت است؛ هر درخواست باید همه چیزِ لازم، از جمله کلید، را داشته باشد.
  • رقم اول کد وضعیت می‌گوید کجا را نگاه کنی: 4xx درخواست خودت، 5xx سرور.
  • GET، PUT و DELETE ایدمپوتنت‌اند؛ POST و PATCH نیستند؛ تکرار POST یعنی چیز تازه.
  • کد وضعیت نوع مشکل را می‌گوید، بدنه خطا جزئیاتش را.
  • خطای شبکه (مثل Connection refused) کد وضعیت ندارد و باید جدا مدیریت شود.

پرسش‌های سنجش

در این درخواست، روش، مسیر، هر هدر و بدنه را جدا کن و بگو هر هدر چه کاری می‌کند.

درخواست زیر به API آزمایشی فرستاده شده است.

PATCH /orders/BS-1002 HTTP/1.1
Host: 127.0.0.1:8787
Authorization: Bearer local-demo-token
Content-Type: application/json

{"carrier": "courier"}
پاسخ نمونه و معیار ارزیابی

روش: PATCH (تغییر بخشی از سفارش). مسیر: /orders/BS-1002. هدرها: Host نشانی سرور؛ Authorization هویت فرستنده با کلید؛ Content-Type می‌گوید بدنه JSON است. بدنه: فیلدی که باید تغییر کند.

  • روش و مسیر درست (1 امتیاز)
  • کار Authorization و Content-Type درست (1 امتیاز)
  • بدنه را بخش تغییر می‌داند (1 امتیاز)
  • Content-Type نوع پاسخ است ← در درخواست، Content-Type نوع بدنه‌ای است که تو می‌فرستی.

برای هر کار روش HTTP مناسب را بنویس و بگو اگر ورک‌فلو آن را دو بار اجرا کند چه می‌شود: (الف) خواندن فهرست سفارش‌های امروز؛ (ب) ساختن تیکت پشتیبانی تازه؛ (ج) حذف یک پیش‌نویس پاسخ؛ (د) تغییر نشانی تحویل یک سفارش.

پاسخ نمونه و معیار ارزیابی

(الف) GET؛ تکرار اثری ندارد. (ب) POST؛ تکرار دو تیکت می‌سازد. (ج) DELETE؛ اثر تکرار همان است (بار دوم احتمالاً 404 ولی چیزی بیشتر حذف نمی‌شود). (د) PATCH (یا PUT اگر کل نشانی جایگزین می‌شود)؛ برای PATCH ایدمپوتنت‌بودن تضمین نیست، هرچند اینجا مقدار یکسان دوباره نوشته می‌شود.

  • چهار روش درست (2 امتیاز)
  • خطر تکرار POST را می‌بیند (1 امتیاز)
  • ب با GET ← GET برای خواندن است؛ ساختن با POST.

ورک‌فلو در یک ساعت این پاسخ‌ها را ثبت کرده است. برای هرکدام بگو ایراد سمت کیست و ورک‌فلو چه باید بکند.

لاگ ساده‌شده.

10:01 GET /orders/BS-1003 -> 200
10:05 GET /orders/BS 1004 -> 404 not_found (unknown endpoint)
10:12 POST /tickets -> 415 unsupported_media_type
10:20 GET /orders/BS-1005 -> 503 temporarily_unavailable
10:21 GET /orders/BS-1005 -> 200
پاسخ نمونه و معیار ارزیابی

10:01 موفق. 10:05 خطای کلاینت: فاصله در شناسه نشانی را خراب کرده (نقطه پایانی ناشناخته، نه سفارش ناموجود)؛ ورودی را پاک‌سازی کن. 10:12 خطای کلاینت: Content-Type جا افتاده؛ تنظیم گره را درست کن، تکرار بی‌فایده است. 10:20 خطای سرور موقت؛ تلاش دوباره درست کار کرد (10:21) و همین رفتار درست است.

  • 10:05 را خطای نشانی می‌داند نه نبود سفارش (1 امتیاز)
  • 10:12 را ایراد هدر و غیرقابل حل با تکرار می‌داند (1 امتیاز)
  • 10:20 را خطای موقت سرور با تلاش دوباره می‌داند (1 امتیاز)
  • همه را دوباره امتحان کن ← 4xx با تکرار همان درخواست درست نمی‌شود.

کدام جمله درباره «ایدمپوتنت» درست است؟

  • یعنی پاسخ دو درخواست یکسان، حتماً یکسان است.
  • یعنی اثر مورد نظر روی سرور با یک بار یا چند بار تکرار یکسان است؛ DELETE ایدمپوتنت است و POST نیست.
  • یعنی درخواست بدنه ندارد.
  • یعنی درخواست حتماً موفق می‌شود.
پاسخ نمونه و معیار ارزیابی
  • a ← DELETE دوم ممکن است 404 بگیرد ولی همچنان ایدمپوتنت است.
  • c ← PUT بدنه دارد و ایدمپوتنت است.
  • d ← ایدمپوتنت‌بودن ربطی به موفقیت ندارد.

درخواستی بنویس (curl یا تنظیمات کلاینت گرافیکی) که در API آزمایشی برای مشتری C-07 یک تیکت با دسته availability و متن «این کتاب را دارید؟» بسازد. پاسخ موفق چه کدی دارد؟

پاسخ نمونه و معیار ارزیابی

curl -H "Authorization: Bearer local-demo-token" -H "Content-Type: application/json" -d '{"customer_ref":"C-07","category":"availability","text":"این کتاب را دارید؟"}' http://127.0.0.1:8787/tickets ؛ پاسخ موفق 201 Created با شناسه تیکت.

  • POST به /tickets (1 امتیاز)
  • هر دو هدر Authorization و Content-Type (1 امتیاز)
  • بدنه JSON معتبر با سه فیلد و کد 201 (1 امتیاز)
  • بدون Content-Type ← API آزمایشی 415 برمی‌گرداند.

فایل‌های درس

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

barg-sabz-mock-api.py

راهنمای کوتاه API آزمایشی

barg-sabz-mock-api.README.md

درخواست و پاسخ‌های ضبط‌شده برای مسیر بدون اجرا

recorded-exchanges.md

ابزارها و جایگزین‌ها

  • Python 3.9 یا بالاتر — اجرای API آزمایشی محلی — مسیر بدون اجرا با پاسخ‌های ضبط‌شده
  • curl یا یک کلاینت HTTP گرافیکی — فرستادن درخواست — Bruno — Insomnia — Postman — گره HTTP Request در n8n

منابع

HTTP: Hypertext Transfer Protocol MDN Web Docs (Mozilla) living doc, accessed 2026-10-16

Idempotent (Glossary) MDN Web Docs (Mozilla) living doc, accessed 2026-10-16

دوره

زبان مشترک نرم‌افزارها: HTTP، JSON و API