اصول طراحی API پایدار و قابل‌گسترش

اول قرارداد، بعد کد

قبل از پیاده‌سازی، OpenAPI را بنویسید. نام فیلد، نوع، اجباری بودن و مثال واقعی را همان‌جا قفل کنید. کلاینت وب و موبایل نباید از روی پاسخ اتفاقی سرور حدس بزنند. این کار اختلاف تیم‌ها را از هفتهٔ سوم به ساعت اول منتقل می‌کند.

اگر محصول چند کلاینت دارد، منبع حقیقت همان قرارداد است، نه یک صفحهٔ ویکی که کهنه می‌شود. مسیر توسعه API ما از این قرارداد شروع می‌شود.

خطا و وضعیت را یک‌بار تعریف کنید

کد HTTP باید معنی داشته باشد: ۴۰۱ برای احراز هویت، ۴۰۳ برای مجوز، ۴۲۲ برای اعتبارسنجی، ۴۲۹ برای محدودیت نرخ. بدنهٔ خطا را یک شکل کنید: کد ماشین‌خوان، پیام انسان‌خوان، و شناسهٔ پیگیری. پیام را به زبان کلاینت بدهید؛ برای محصول فارسی، متن پشتیبانی فارسی جلوتر از کلید انگلیسی خام است.

لیست را صفحه‌بندی کنید و ترتیب پیش‌فرض را بنویسید. بدون این دو، موبایل در صفحهٔ دوم دادهٔ تکراری می‌بیند و هیچ‌کس مقصر را پیدا نمی‌کند.

نسخه‌گذاری یعنی قول به کلاینت قدیمی

نسخه را در مسیر یا هدر بگذارید و همان را تا پایان عمر نسخه نگه دارید. فیلد جدید اختیاری معمولاً سازگار است. حذف فیلد، تغییر نوع، یا عوض شدن معنای وضعیت شکننده است و باید نسخهٔ جدید باشد.

تاریخ بازنشستگی نسخهٔ قدیم را اعلام کنید و در این فاصله هر دو را زنده نگه دارید. قطع ناگهانی اپ استور را گروگان می‌گیرد.

احراز هویت و محدودهٔ دسترسی را در قرارداد بیاورید

بگویید کدام مسیر عمومی است، کدام session می‌خواهد، و کدام توکن. نمونهٔ درخواست واقعی با هدر CSRF یا Authorization را در مستند بگذارید. اگر مرورگر و اپ موبایل مدل متفاوتی دارند، هر دو را بنویسید تا یک تیم از دیگری کپی غلط نکند.

Webhook را با امضا، تکرار و پاسخ سریع طراحی کنید. اگر پردازش طولانی است، اول ۲۰۰ بدهید و بعد کار را در صف انجام دهید.

مستنداتی که کسی واقعاً باز می‌کند

نمونهٔ curl یا مجموعهٔ Postman، محیط آزمایش، و changelog کوتاه پذیرش را بالا می‌برد. بعد از هر تغییر شکننده یک بند در changelog بنویسید؛ حافظهٔ شفاهی تیم کافی نیست.

Sandbox را با دادهٔ ساختگی ولی شکل واقعی پر کنید. کلاینت نباید برای اولین تست به دیتابیس تولید وصل شود.

جمع‌بندی

API پایدار یعنی قرارداد جلوتر از کد، خطاهای قابل‌پیش‌بینی، نسخهٔ محترم، و مستند زنده. این‌ها هزینهٔ اولیه دارند و هزینهٔ بعدی را کم می‌کنند. اگر چند کلاینت به یک بک‌اند وصل می‌شوند، طراحی قرارداد را با ما شروع کنید.