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