فصل ۱ — مبانی API و HTTP
HTTP برای API — متد، کد وضعیت و هدرفصل ۲ — طراحی REST
منابع، آدرسها و ساختار REST درستفصل ۳ — امنیت و نسخهبندی
احراز API: API Key، JWT و OAuth 2 نسخهبندی، CORS و مدیریت خطای منظمفصل ۴ — مصرف API و کیفیت
مصرف API از فرانت: fetch، retry و حالتهای UIپروژه عملی پایان دوره
پروژه پایانی — API فروشگاه کوچک با احراز، CORS و مستنداتنسخهبندی، CORS و مدیریت خطای منظم
API زنده یعنی تغییر میکند؛ نسخهبندی (/v1/) اجازه تغییر بدون شکستن کلاینتها میدهد. CORS قرارداد مرورگر برای درخواستهای بیندامنه است — پیکربندی غلطش بزرگترین گلوگاه توسعه است. و خطاها باید منظم باشند: کد ماشینی + پیام انسانی + جزئیات اعتبارسنجی.
مراحل قدمبهقدم
-
۱
نسخهبندی عملی
در مسیر: /v1/ و /v2/ موازی؛ تغییر ناسازگار (حذف فیلد، تغییر معنا) یعنی نسخه جدید؛ تغییر سازگار (فیلد جدید اضافه) در نسخه فعلی مجاز. اعلام تاریخ_EOL برای نسخههای قدیمی و هدر هشدار برای کلاینتهای نزدیک به منقضی.
-
۲
CORS درست
مرورگر پیش از درخواست بیندامنهای با هدر سفارشی، OPTIONS میپرسد (preflight). پاسخ سرور: Access-Control-Allow-Origin با دامنه دقیق (هرگز * برای API احرازدار)، Allow-Methods و Allow-Headers مناسب. در Express پکیج cors با whitelist.
-
۳
قالب خطای منظم
{ error: { code: 'validation', message: 'پیام فارسی', fields: { email: 'ایمیل نامعتبر' } } } — کد ماشینی برای منطق کلاینت، message برای نمایش، fields برای فرم. یک Error Handler مرکزی همه خطاها را به این قالب میریزد.
-
۴
مستندسازی OpenAPI
فایل openapi.yaml قلب مستندات: مسیرها، متدها، اسکیمای ورودی/خروجی و کدهای وضعیت. از آن، UI تعاملی (Swagger UI/Scalar) و حتی تستهای قراردادی تولید میشود. مستندِ بهروز = قرارداد قابل اعتماد؛ مستند دستی منقضی = فریب.
نکات مهم
- ◆ تغییر ناسازگار = نسخه جدید؛ فیلد حذفشده بدون نسخه جدید، کلاینتها را میشکند.
- ◆ CORS با دامنههای صریح؛ * فقط برای APIهای عمومی بدون احراز.
- ◆ خطا همیشه یک قالب؛ fields برای فرمها حیاتی است.
کد یا مسیر نمونه
const cors = require("cors");
app.use(cors({
origin: ["https://radikalwp.ir", "http://localhost:3000"],
methods: ["GET", "POST", "PATCH", "DELETE"],
allowedHeaders: ["Content-Type", "Authorization"],
credentials: true,
}));
// خطای مرکزی:
app.use((err, req, res, next) => {
if (err.name === "ValidationError") {
return res.status(422).json({
error: { code: "validation", message: "داده ارسالی نامعتبر است", fields: err.fields },
});
}
console.error(err);
res.status(500).json({ error: { code: "server", message: "خطای داخلی سرور" } });
});
// openapi.yaml (خلاصه):
// paths:
// /v1/orders:
// post:
// security: [ bearerAuth: [] ]
// requestBody: { $ref: '#/components/schemas/OrderInput' }
// responses:
// '201': { description: 'ساخته شد' }
// '422': { description: 'اعتبارسنجی ناموفق' }
اجرای زنده کد JavaScript
کد را ویرایش کنید و «اجرای کد» را بزنید — خروجی واقعی مرورگر همینجا رندر میشود؛ مثل آزمایشگاه w3schools.
پرسش و پاسخ این درس (۰)
هنوز دیدگاهی ثبت نشده؛ اولین نفر باشید!