فصل ۱ — مبانی API و HTTP
HTTP برای API — متد، کد وضعیت و هدرفصل ۲ — طراحی REST
منابع، آدرسها و ساختار REST درستفصل ۳ — امنیت و نسخهبندی
احراز API: API Key، JWT و OAuth 2 نسخهبندی، CORS و مدیریت خطای منظمفصل ۴ — مصرف API و کیفیت
مصرف API از فرانت: fetch، retry و حالتهای UIپروژه عملی پایان دوره
پروژه پایانی — API فروشگاه کوچک با احراز، CORS و مستنداتHTTP برای API — متد، کد وضعیت و هدر
API یعنی قرارداد گفتگو بین دو برنامه با HTTP. متد قصد را میگوید (GET خواندن، POST ساخت، PUT تغییر کامل، PATCH تغییر جزئی، DELETE حذف)، کد وضعیت نتیجه را (200/201/400/401/403/404/422/429/500) و هدرها متادیتا (Content-Type، Authorization، Rate Limit). API خوب یعنی استفاده از این مفاهیم درست و مستند.
مراحل قدمبهقدم
-
۱
متدها و معنای واقعی
GET امن و idempotent (دوبارهزنی اثر ندارد)؛ POST نه idempotent (دو POST = دو سفارش!)؛ PUT و DELETE idempotent؛ PATCH جزئی. قاعده: تغییر حالت با GET ممنوع — لینکپیشبارگذاری مرورگر و crawler آن را اجرا میکند.
-
۲
کدهای وضعیت درست
200 OK، 201 Created (با Location)، 204 No Content (حذف)، 400 درخواست بدشکل، 401 نشده احراز، 403 ایدهدار ولی مجاز نیست، 404 نیست، 409 تداخل، 422 اعتبارسنجی، 429 نرخ، 500 خطای سرور. استفاده از 200 برای همهچیز معنای قرارداد را میکشد.
-
۳
هدرهای مهم
Content-Type: application/json برای بدنه JSON؛ Authorization: Bearer token؛ Accept درخواست فرمت؛ Cache-Control و ETag برای کش. هدر Rate Limit (X-RateLimit-Remaining) به کلاینت شفافیت میدهد.
-
۴
بدنه و فرمت پاسخ
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
کد را ویرایش کنید و «اجرای کد» را بزنید — خروجی واقعی مرورگر همینجا رندر میشود؛ مثل آزمایشگاه w3schools.
پرسش و پاسخ این درس (۰)
هنوز دیدگاهی ثبت نشده؛ اولین نفر باشید!