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