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