منابع را با اسم و مسیر جمع مانند نمونهٔ زیر معرفی کنید.
/users
راهنمای طراحی endpointهای قابل پیشبینی، نسخهپذیر و قابل استفاده برای کلاینتها. منابع را با اسم و مسیر جمع مانند `/users` معرفی کنید. از متدهای HTTP متناسب استفاده کنید: GET خواندن، POST ایجاد، PUT/PATCH تغییر، DELETE حذف. کدهای وضعیت دقیق برگردانید؛ موفقیت، ورودی نامعتبر، عدم احراز هویت و خطای سرور را تفکیک کنید. از این صفحه بهعنوان مرجع سریع استفاده کنید و مثالها و نکتهها را با نسخهٔ ابزار، نیاز و شرایط واقعی پروژهٔ خود تطبیق دهید.
منابع را با اسم و مسیر جمع مانند نمونهٔ زیر معرفی کنید.
/usersاز متدهای HTTP متناسب استفاده کنید: GET خواندن، POST ایجاد، PUT/PATCH تغییر، DELETE حذف.
کدهای وضعیت دقیق برگردانید؛ موفقیت، ورودی نامعتبر، عدم احراز هویت و خطای سرور را تفکیک کنید.
ساختار پاسخ و خطا را پایدار، مستند و بدون افشای جزئیات حساس نگه دارید.
اعتبارسنجی ورودی و کنترل مجوز را برای هر منبع در سمت سرور انجام دهید.
فهرستها را با pagination محدود کنید و فیلتر و sort را whitelist کنید.
برای تغییرات ناسازگار، سیاست versioning و دورهٔ مهاجرت مشخص داشته باشید.
در عملیات تکرارپذیر، رفتار idempotency و retry را تعریف کنید.
محدودیت نرخ، timeout و اندازه بدنه را بر اساس مصرف تنظیم کنید.
قرارداد API را با schema، مثال و تست integration همگام نگه دارید.
برای پاسخ cacheپذیر از ETag و If-None-Match استفاده کنید و دادهٔ خصوصی را عمومی cache نکنید.
ETagIf-None-Matchرفتار idempotent متدها را از اثر retry در کلاینت جدا کنید و برای درخواست ساخت تکرارپذیر کلید idempotency تعریف کنید.