بازگشت به بلاگنکات حرفه‌ای برنامه‌نویسان
چگونه یک API مستند و قابل‌نگهداری طراحی کنیم؟
۴ شهریور ۱۴۰۵
نویسنده:
نیما کاظمی
یک API خوب، API ای است که بدون نیاز به پرسیدن از نویسنده‌اش، قابل‌استفاده باشد.
- از نام‌گذاری یکدست برای endpoint ها استفاده کنید (jsonمثلاً همیشه جمع:
/posts، نه گاهی/post). - کدهای وضعیت HTTP را درست و معنادار برگردانید (۴۰۴، ۴۲۲، ۴۰۱ و...).
- برای تغییرات breaking، از versioning استفاده کنید (مثل
/v1/). - مستندات را هم‌زمان با کد به‌روز نگه دارید؛ ابزارهایی مثل OpenAPI کمک زیادی می‌کنند.
زمانی که برای مستندسازی می‌گذارید، مستقیماً در تعداد سؤال‌هایی که بعداً باید جواب بدهید صرفه‌جویی می‌کند.