تعویض کلاینت API اغلب با داستان رنج شروع می‌شود. یک تب برای مستند، یک تب برای فرستادن درخواست، یک چیز جدا برای داده تقلبی، و هیچ‌کدام با هم حرف نمی‌زنند. مشخصات را در یک جا عوض می‌کنی و در جای دیگر هنوز شکل قدیمی را صدا می‌زنی. این درد واقعی است. نتیجه‌ای که از آن گرفته می‌شود گاهی غلط است: اینکه باید همه این کارها را به یک محصول بسپاری و همان محصول، قرارداد را نگه دارد.
قرارداد API مال مخزن است. OpenAPI یا هر توصیف متنی دیگری که در بازبینی دیده شود، با کد سرویس نسخه می‌خورد، و بدون حساب کاربری یک فروشنده قابل خواندن است. کلاینت، پنجره‌ای روی همان قرارداد است. اگر پنجره خودش تنها نسخه «آخر» باشد، تو مشکل چندابزاری را حل نکرده‌ای. فقط همه تخم‌مرغ‌ها را در یک سبد بسته‌ای که خروجی متنی تمیز ندارد.
کلاینت چه کاری باید بکند
کار اصلی کلاینت این است که یک درخواست واقعی را با احراز هویت همان محیط بسازی، جواب را بخوانی، و بتوانی همان درخواست را برای هم‌تیمی تکرار کنی. اگر این سه تا را خوب انجام دهد، برای خیلی از تیم‌ها کافی است. مجموعه درخواست باید قابل diff باشد. محیطی که آدرس و متغیر را جدا از راز نگه می‌دارد باید معلوم باشد. راز نباید داخل فایلی بنشیند که راحت به چت یا به مخزن عمومی می‌رود.
کار دوم، چسبیدن به مشخصات است. اگر از روی OpenAPI می‌توانی درخواست نمونه بسازی و اگر مشخصات عوض شد اختلاف را می‌بینی، کلاینت دارد به قرارداد خدمت می‌کند. اگر کلاینت مشخصات را وارد می‌کند و بعد نسخه داخلی خودش را منبع حقیقت می‌کند، خدمت برعکس شده. هر تغییری باید از همان جایی بیاید که کد سرور از آن می‌آید. وگرنه دوباره سه نسخه «آخر» داری، فقط داخل یک برند.
mock وقتی مفید است که از همان مشخصات ساخته شود و برای توسعه کلاینت، سرور هنوز آماده نباشد. mockی که دستی در یک محصول جدا نگهداری می‌شود خیلی زود از واقعیت فاصله می‌گیرد. فرانت روی شکل قدیمی جلو می‌رود و روز اتصال، باگ را «ناسازگاری غیرمنتظره» می‌نامید. غیرمنتظره نبود. دو منبع داشتی.
چه وقتی ابزار یک‌جا ارزش دارد
ابزار یک‌جا وقتی می‌ارزد که خروجی‌اش هنوز متن قابل بازبینی باشد و تیم را گروگان قالب خصوصی نکند. مثلاً مجموعه را به صورت فایل در ریپو نگه دارد، یا مستقیم از OpenAPI بخواند و چیزی را که نمی‌شود diff گرفت به‌عنوان منبع نپذیرد. در این حالت یکپارچگی واقعی است: یک جا درخواست می‌زنی، مستند از همان توصیف تولید می‌شود، و تغییر در PR دیده می‌شود.
ارزش دوم برای کسانی است که کد سرور را نمی‌نویسند ولی باید API را بفهمند: فرانت، QA، یا پشتیبانی فنی. یک رابط که احراز هویت محیط آزمایشی را درست تزریق می‌کند و نمونه خطا را نشان می‌دهد، از خواندن JSON خام برای آن‌ها بهتر است. این دلیل خوبی برای داشتن کلاینت است. دلیل خوبی برای منتقل کردن مالکیت قرارداد از ریپو به آن کلاینت نیست.
ارزش سوم، درخواست‌های سخت UI است: چندبخشی، کوکی، زنجیره فراخوان که خروجی یکی ورودی بعدی است. این‌ها در curl ممکن‌اند و در یک رابط مرتب سریع‌تر آموزش داده می‌شوند. اگر تیم زیاد این شکل درخواست را دیباگ می‌کند، کلاینت گرافیکی وقت ورود تازه‌وارد را کم می‌کند. باز هم مجموعه را طوری نگه دار که بدون آن رابط هم قابل فهم باشد.
چه وقتی ساده‌تر کافی است
اگر API کوچک است و مصرف‌کننده‌اش فقط همین مخزن است، یک فایل curl یا یک تست یکپارچه که همان درخواست را می‌زند اغلب از یک کلاینت سنگین بهتر است. تست در CI زنده می‌ماند. مجموعه گرافیکی که فقط روی لپ‌تاپ یک نفر به‌روز است، مستند مرده است. برای کتابخانه داخلی، تست قرارداد و مثال در README ممکن است کل نیاز باشد.
اگر تیم هنوز مشخصات ندارد، خریدن ابزاری که «مستند را هم می‌سازد» وسوسه‌انگیز است. اول بپرس آن مستند از کجا به‌روز می‌شود. اگر جواب «از داخل همان ابزار و با دست» است، تو فرآیند دوم ساختی. بهتر است مشخصات را از کد یا از یک فایل در ریپو دربیاوری، حتی اگر روز اول ناقص باشد. کلاینت را بعد انتخاب کن، وقتی چیزی هست که باید به آن وفادار بماند.
تعویض ابزار هم هزینه دارد. تاریخچه درخواست، محیط‌ها، و عادت تیم جابه‌جا نمی‌شوند فقط چون محصول جدید تب‌های بیشتری را یکی کرده. قبل از مهاجرت، یک مسیر واقعی را با ابزار جدید تا آخر برو: از مشخصات تا درخواست احراز هویت‌شده روی محیط آزمایشی، به‌علاوه یک تغییر کوچک در قرارداد که باید در PR دیده شود. اگر این مسیر گیر کرد، ویژگی‌های اضافه مهم نیستند.
معیار انتخاب بدون وابستگی به فروشنده
این‌ها را بپرس و به نام محصول امتیاز نده. آیا منبع حقیقت در git می‌ماند؟ آیا راز از فایل اشتراک‌گذاری‌شده جداست؟ آیا می‌شود یک درخواست را بدون حساب ابری فروشنده تکرار کرد؟ آیا اختلاف مشخصات با پیاده‌سازی جایی نمایان می‌شود که تیم همان‌جا کد را بازبینی می‌کند؟ آیا خروج از ابزار ممکن است، یعنی خروجی استاندارد داری نه فقط پروژه خصوصی؟
اگر چهار تا از این پنج تا منفی است، یکپارچگی ظاهری را نخر. درد چند تب را با انضباط یک مشخصات حل کن و کلاینت را سبک نگه دار. اگر هر پنج تا مثبت است، آن وقت ابزار هر نامی داشته باشد قابل دفاع است. دلیل دفاع، قابلیت‌های صفحه قیمت نیست. این است که قرارداد تیم هنوز مال تیم مانده.
پرسش‌های کوتاه
پس ابزار همه‌کاره همیشه غلط است؟ نه. غلط است وقتی تنها کپی قرارداد می‌شود. درست است وقتی نمایی روی قراردادی است که در ریپو زندگی می‌کند.
curl برای تیم محصول کافی است؟ برای دیباگ روزمره خیلی‌ها نه. برای منبع حقیقت بله، اگر کنار مشخصات و تست باشد. کلاینت گرافیکی جای تست CI را نمی‌گیرد.
مجموعه درخواست را کجا نگه دارم؟ کنار همان سرویسی که API را پیاده می‌کند، در شکلی که diff دارد. اگر فقط در فضای ابری یک حساب شخصی است، مال تیم نیست.