API & REST Tutorial فصل ۱ — مبانی API و HTTP درس آموزشی

HTTP برای API — متد، کد وضعیت و هدر

API یعنی قرارداد گفتگو بین دو برنامه با HTTP. متد قصد را می‌گوید (GET خواندن، POST ساخت، PUT تغییر کامل، PATCH تغییر جزئی، DELETE حذف)، کد وضعیت نتیجه را (200/201/400/401/403/404/422/429/500) و هدرها متادیتا (Content-Type، Authorization، Rate Limit). API خوب یعنی استفاده از این مفاهیم درست و مستند.

مراحل قدم‌به‌قدم

  1. ۱

    متدها و معنای واقعی

    GET امن و idempotent (دوباره‌زنی اثر ندارد)؛ POST نه idempotent (دو POST = دو سفارش!)؛ PUT و DELETE idempotent؛ PATCH جزئی. قاعده: تغییر حالت با GET ممنوع — لینک‌پیش‌بارگذاری مرورگر و crawler آن را اجرا می‌کند.

  2. ۲

    کدهای وضعیت درست

    200 OK، 201 Created (با Location)، 204 No Content (حذف)، 400 درخواست بدشکل، 401 نشده احراز، 403 ایده‌دار ولی مجاز نیست، 404 نیست، 409 تداخل، 422 اعتبارسنجی، 429 نرخ، 500 خطای سرور. استفاده از 200 برای همه‌چیز معنای قرارداد را می‌کشد.

  3. ۳

    هدرهای مهم

    Content-Type: application/json برای بدنه JSON؛ Authorization: Bearer token؛ Accept درخواست فرمت؛ Cache-Control و ETag برای کش. هدر Rate Limit (X-RateLimit-Remaining) به کلاینت شفافیت می‌دهد.

  4. ۴

    بدنه و فرمت پاسخ

    JSON استاندارد صنعت است؛ ساختار ثابت (مثلاً {data, meta, error}) و تاریخ ISO 8601 با timezone. پوشش خطا همیشه با پیام فارسی/انگلیسی ثابت و کد ماشینی (error_code) تا کلاینت تصمیم برنامه‌ای بگیرد.

نکات مهم

  • ◆ GET هرگز اثر جانبی ندارد؛ تغییر با GET = باگ طراحی.
  • ◆ کد وضعیت درست بدهید؛ 200-همه‌جا قرارداد را بی‌معنا می‌کند.
  • ◆ فرمت پاسخ و خطا یکسان و مستند — کلاینت‌ها به آن تکیه می‌کنند.

کد یا مسیر نمونه

// درخواست نمونه با fetch:
const res = await fetch("https://api.example.com/v1/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer eyJhbGc...",
  },
  body: JSON.stringify({ item_id: 42, qty: 2 }),
});

if (res.status === 201) {
  const order = await res.json();   // { data: {...} }
  console.log("سفارش ساخته شد:", order.data.id);
} else if (res.status === 422) {
  const err = await res.json();
  console.log("اعتبارسنجی:", err.error.message);
}

// پاسخ استاندارد مورد انتظار:
// 201 Created
// { "data": { "id": 101, "status": "pending" } }
// خطا:
// 422 { "error": { "code": "validation", "message": "تعداد باید بین ۱ تا ۱۰ باشد" } }

اجرای زنده کد JavaScript

editor.html
در حال آماده‌سازی زمین بازی…

کد را ویرایش کنید و «اجرای کد» را بزنید — خروجی واقعی مرورگر همین‌جا رندر می‌شود؛ مثل آزمایشگاه w3schools.

پرسش و پاسخ این درس (۰)

هنوز دیدگاهی ثبت نشده؛ اولین نفر باشید!

دیدگاه خود را بنویسید

کپچا

دیدگاه شما پس از تأیید مدیر نمایش داده می‌شود.