قرارداد مشخص و قابل پیشبینی برای تبادل داده بین کلاینت و سرور؛ ستون فقرات وباپهای مدرن. در این آموزش، مسیر را به گامهای کوچک و قابلاجرا شکستهایم تا بدون سردرگمی پیش بروید. هر اپلیکیشن ایرانی که با سرور حرف میزند از یک API استفاده میکند؛ طراحی بد یعنی دو برابر شدن کار کلاینت.
قبل از شروع چه چیزهایی لازم دارید؟
- ده تا پانزده دقیقه وقتِ بدون وقفه برای مطالعهٔ این صفحه
- دسترسی به منبع اصلی: Zod/اعتبارسنجی
- یک یادداشت برای ثبت گامهایی که انجام میدهید
گامهای اصلی
مسیر پیشنهادی به ترتیب زیر است؛ هر گام را کامل کنید و بعد سراغ بعدی بروید:
- منابع را اسم بگذارید (users/posts) نه عملیات (getUsers)
- از کدهای وضعیت HTTP درست استفاده کنید (201 برای ساخت، 404 برای نبودن)
- صفحهبندی را از روز اول طراحی کنید
این سه گام، ستون فقرات کار است؛ باقی مسیر تکرار و بهبود همین سه گام است.
گامهای تکمیلی
وقتی پایه را ساختید، این موارد نتیجه را چند برابر میکند:
- خطاها را با ساختار یکسان برگردانید
- نسخهبندی را از /v1 شروع کنید
اگر گیر کردید
هر کس در این مسیر گیر میکند؛ تفاوت در واکنش است:
- به جای شروع دوباره از صفر، فقط همان گامِ گیرکرده را مرور کنید
- مشکل را جستوجو کنید؛ احتمالاً قبلاً کسی همان سؤال را پرسیده (REST یا GraphQL پرسش رایجی است)
- از منابع معرفیشده در ادامه کمک بگیرید
ابزارها و منابع مسیر
| منبع / ابزار | چه استفادهای؟ |
|---|---|
| Postman/Insomnia | تست و مستندسازی دستی |
| OpenAPI/Swagger | قرارداد زندهٔ مستند |
| Zod/اعتبارسنجی | دروازهٔ دادهٔ ورودی |
| Bruno/کلاینت گیتپذیر | کالکشن API کنار کد |
اشتباهاتی که مسیر را کج میکنند
- برگرداندن ۲۰۰ با پیام خطا داخل بدنه
- اندپوینتهای فعلمحور بهسبک RPC
- بیصفحهبندی روی جداول رشدپذیر
پرسشهای رایج در حین یادگیری
REST یا GraphQL؟
برای اکثر پروژهها REST سادهتر و کافی است؛ GraphQL وقتی کلاینتهای متفاوت دادههای متفاوت میخواهند.
احراز هویت API چطور؟
توکنهای کوتاهعمر + refresh؛ کلید ثابت در URL هرگز.
مستندات را چطور زنده نگه دارم؟
از OpenAPI بهعنوان منبع یکتا و تولید مستند از خود کد.
جمعبندی
طراحی REST API را وقتی درست به کار بگیرید، هم زمان میدهد و هم کیفیت. مسیر ساده بود: شروع کنید، اندازه بگیرید و اصلاح کنید. اگر همین امروز دو سه مورد از این فهرست را اجرا کنید، تفاوت را در هفتههای بعد خواهید دید.
دیدگاهها
۰ دیدگاههنوز دیدگاهی ثبت نشده؛ اولین نفر باشید.