طراحی RESTful API یک فرآیند پیچیده است که شامل عوامل زیادی از جمله مقیاس پذیری، عملکرد، امنیت و تجربه کاربر است. این برگه تقلب یک مرجع سریع برای بهترین شیوه ها و مشکلات رایج برای جلوگیری از طراحی API های RESTful ارائه می دهد.
روش های درخواست HTTP
روش های درخواست HTTP/ افعال HTTP برای انجام عملیات روی منابع در یک RESTful API استفاده می شود. هر فعل HTTP هدف خاصی دارد و استفاده صحیح از آنها برای ثبات و امنیت API ضروری است. در اینجا رایج ترین افعال HTTP و کاربرد آنها آورده شده است:
- GET: بازیابی یک منبع
- POST: ایجاد یک منبع جدید یا انجام یک عمل در یک منبع
- PUT: یک منبع موجود را به روز کنید
- PATCH: به‌روزرسانی بخشی از یک منبع موجود
- DELETE: حذف یک منبع
قراردادهای نامگذاری
قراردادهای نامگذاری منابع برای خوانایی و قابلیت استفاده API بسیار مهم هستند. در اینجا برخی از بهترین روش ها برای نامگذاری منابع آورده شده است:
- استفاده از اسامی جمع برای مجموعه منابع (به عنوان مثال، /users)
- از اسامی مفرد برای منابع فردی استفاده کنید (مثلاً /users/123)
- از حروف کوچک و خط تیره برای نام منابع استفاده کنید (مثلاً /users/123/orders)
- از اسم ها به جای افعال در نام منابع استفاده کنید (به عنوان مثال، /orders/123 به جای /get-order/123)
صفحه بندی منابع
صفحه بندی منابع در هنگام برخورد با مجموعه های بزرگ منابع ضروری است. در اینجا برخی از بهترین شیوه ها برای صفحه بندی منابع آورده شده است:
- از پارامترهای محدود و افست برای صفحه بندی استفاده کنید (به عنوان مثال /users?limit=10&offset=20)
- از یک محدودیت پیش‌فرض استفاده کنید و به مشتری اجازه دهید افست را کنترل کند
- شامل متاداده صفحه بندی در سرصفحه های پاسخ (به عنوان مثال، X-Total-Count)
پاسخ های خطا
پاسخ های خطا برای قابلیت استفاده API بسیار مهم هستند و باید در سراسر API سازگار باشند. در اینجا برخی از بهترین روش ها برای پاسخ به خطا آورده شده است:
از کدهای وضعیت HTTP برای نشان دادن نوع خطا استفاده کنید (به عنوان مثال، 400 برای درخواست بد، 401 برای غیرمجاز، 404 برای یافت نشد، 500 برای خطای سرور داخلی)
- یک پیام خطای توصیفی را در بدنه پاسخ قرار دهید
- از یک قالب خطای ثابت در سراسر API استفاده کنید
احراز هویت و مجوز
احراز هویت و مجوز برای امنیت API ضروری است. در اینجا برخی از بهترین روش ها برای احراز هویت و مجوز وجود دارد:
- استفاده از مکانیزم احراز هویت امن (به عنوان مثال، OAuth 2.0، JWT)
- از HTTPS برای ارتباط امن استفاده کنید
- از کنترل دسترسی مبتنی بر نقش (RBAC) برای محدود کردن دسترسی به منابع استفاده کنید
- از دامنه های مناسب برای محدود کردن دسترسی به اقدامات خاص استفاده کنید
نسخه سازی
زمانی که تغییراتی در API ایجاد می‌شود، نسخه‌سازی API ضروری است، و سازگاری با عقب باید حفظ شود. در اینجا برخی از بهترین روش ها برای نسخه API آورده شده است:
- از یک شماره نسخه در URI استفاده کنید (به عنوان مثال، /v1/users)
- از یک هدر نسخه در درخواست استفاده کنید (به عنوان مثال، Accept-Version: v1)
- نسخه های قدیمی را منسوخ کنید و یک مسیر مهاجرت ارائه دهید
ذخیره سازی
حافظه پنهان می تواند عملکرد API را بهبود بخشد و بار سرور را کاهش دهد. در اینجا برخی از بهترین روش ها برای ذخیره API وجود دارد:
- از هدرهای کش مناسب استفاده کنید (به عنوان مثال، Cache-Control، Expires)
- از ETag ها برای اعتبارسنجی منابع استفاده کنید
- استفاده از یک شبکه تحویل محتوا (CDN) را برای ذخیره سازی در نظر بگیرید
HATEOAS
HATEOAS (Hypermedia به عنوان موتور حالت برنامه) یک اصل طراحی API RESTful است که به مشتریان امکان می دهد منابع را به صورت پویا کشف کرده و با آنها تعامل داشته باشند. در اینجا برخی از بهترین روش ها برای استفاده از HATEOAS آورده شده است:
- پیوندهایی به منابع مرتبط را در پاسخ قرار دهید
- استفاده از روابط استاندارد پیوند (به عنوان مثال، خود، بعدی، قبلی)
- از انواع رسانه ای استفاده کنید که از هایپر مدیا پشتیبانی می کنند (مانند HAL، JSON-LD)
من این cheatsheet REST API را برای کمک به تولید/برنامه ریزی اسناد API خودم جمع آوری کردم، امیدوارم برای کسی که می خواند مفید باشد.
