HTTP Requests and Responses for Workflow Builders
Learn the parts of an HTTP request and response, call a practice API and read what happened from the status code.
بعد از این درس میتوانی
- اجزای درخواست 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
این تشبیه کجا غلط است؟ باجه اداره ممکن است تو را بشناسد و پروندهات را به خاطر بیاورد. 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) یک درخواست تازه بساز:
GET http://127.0.0.1:8787/healthبدون هیچ هدری. باید 200 بگیری.GET http://127.0.0.1:8787/orders/BS-1001بدون هدر. باید 401 بگیری؛ بدنه را بخوان.- همان را با هدر
Authorizationو مقدارBearer local-demo-tokenدوباره بفرست. 200 و جزئیات سفارش. 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 دقیقه
هدف: خواندن پاسخ و تصمیم.
گامها: برای هر پاسخ بنویس کلاس، معنی و اینکه ورکفلو چه کند (ادامه، اصلاح درخواست، تلاش دوباره، توقف و هشدار).
201 Createdبا بدنه تیکت تازه.400با{"error": {"code": "validation_error", "message": "missing or non-string fields: text"}}403 Forbidden503باtemporarily_unavailable404برای نشانی/order/BS-1001(بدون s)
معیار پذیرش: هر پنج مورد درست؛ مورد ۵ بهعنوان نشانی غلط، نه «سفارش نیست».
راهحل نمونه
۱: موفق؛ ادامه و ثبت شناسه تیکت. ۲: خطای کلاینت؛ فیلد text را اضافه کن، تکرار بیفایده است. ۳: خطای کلاینت؛ کلید هست ولی اجازه ندارد؛ توقف و هشدار به مسئول دسترسی. ۴: خطای سرور؛ تلاش دوباره با فاصله، بعد صف انسانی. ۵: خطای کلاینت؛ مسیر غلط است (/orders درست است)؛ درخواست را اصلاح کن.
چالش
تمرین · 30 دقیقه
موقعیت: در درس آخر دوره پایه برای کار خودت طرح خودکارسازی نوشتی. حالا گامهایی را که به یک سامانه دیگر وصل میشوند، به درخواست HTTP تبدیل کن. اگر مستندات API واقعی آن سامانه را نداری یا دادهاش حساس است، یک API ساختگی با همان شکل فرض کن.
- برای هر اتصال، یک «کارت درخواست» بنویس: روش، نقطه پایانی، هدرها (بدون مقدار واقعی کلید)، بدنه نمونه و پاسخ موفق نمونه.
- برای هر کارت، سه پاسخ ناموفق محتمل (یک 4xx، یک 5xx، یک خطای شبکه) و رفتار ورکفلو برای هرکدام را بنویس.
- بگو کدام درخواستها اثر تکراری دارند و اگر دو بار اجرا شوند چه میشود.
خروجی مورد انتظار: دستکم دو کارت درخواست با پاسخ موفق، سه پاسخ ناموفق و رفتار هرکدام، و علامت «اثر تکراری» برای هر درخواست.
معیار پذیرش:
- روش هر درخواست با کارش جور است.
- هیچ کلید یا داده واقعی در کارتها نیست؛ نمونهها ساختگی یا ناشناساند.
- رفتار 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