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