توسعه API

این خدمت برای چه اتصالی است؟

توسعه API یعنی قرارداد پایدار بین سیستم‌ها: اپ موبایل، فرانت وب، سرویس حسابداری، یا محصول ثالث. مخاطب: تیمی که چند کلاینت دارد و نمی‌خواهد هر بار فیلد را شفاهی عوض کند.

خروجی REST یا GraphQL است با نسخه‌بندی، محدودیت نرخ، و مستند OpenAPI. وب‌هوک وقتی سیستم شما باید رویداد را هل بدهد، نه فقط پول کند.

همین الگو در محصول‌های خودمان هست: فرانت نوبیتا از API نسخه‌بندی Django می‌خواند. صفحهٔ محصول را با این خدمت اشتباه نگیرید؛ اینجا API سفارشی شما ساخته می‌شود.

API خوب چه شکلی است؟

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

مستند Swagger/OpenAPI همراه مجموعهٔ Postman در تحویل است. SDK را وقتی چند زبان کلاینت دارید می‌نویسیم؛ وگرنه مستند و مثال curl کافی است.

فرآیند

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

اگر بک‌اند دامنهٔ کسب‌وکار هنوز نیست، این خدمت را با بک‌اند Django یکی می‌کنیم تا API روی هوا نماند.

استقرار و کلیدها با DevOps: محیط، راز، و لاگ بدون نشت توکن.

استک

Django REST، در صورت تناسب FastAPI، GraphQL، OpenAPI. GraphQL را برای فیلد تودرتوی کلاینت‌های متعدد می‌گذاریم؛ برای یک کلاینت داخلی REST معمولاً ساده‌تر است.

خروجی

API production، مستند Swagger، مجموعهٔ Postman، تست خودکار. مالکیت مشخصات و کد پس از تسویه با شماست.

چه وقت این خدمت را نگیرید؟

اگر فقط یک فرم تماس روی سایت می‌خواهید، API عمومی لازم نیست. اگر ERP می‌خواهید، Odoo است.

پرسش‌های پرتکرار

نسخهٔ v2 را کی شروع کنیم؟

وقتی تغییر، کلاینت قدیمی را می‌شکند. تا آن روز فیلد اختیاری اضافه می‌کنیم، حذف نمی‌کنیم.

وب‌هوک امن یعنی چه؟

امضا، مهلت، و تلاش مجدد با idempotency. جزئیات در طراحی همان پروژه است.

درخواست را در تماس بنویسید.

در جلسه کشف نیاز API چه می‌پرسیم؟

چه کلاینتی امروز وجود دارد و چه کلاینتی شش ماه دیگر می‌آید. آیا مصرف‌کنندهٔ خارجی هست؛ اگر هست، کلید، سهمیه و قرارداد استفاده جدا نوشته می‌شود.

سازگاری عقب‌رو: آیا اپ قدیمی در بازار است که نتوانید فیلد را حذف کنید. نسخه‌بندی از روز اول ارزان‌تر از مهاجرت اضطراری است.

وب‌هوک و رویداد

اگر سیستم مقابل گاهی پایین است، صف و تلاش مجدد لازم است. بدون idempotency، پرداخت یا ثبت تکراری می‌سازید. این را در تست خودکار می‌آوریم، نه فقط در مستند.

هفتهٔ اول سه مسیر: سلامت سرویس، یک GET و یک POST با خطاهای مشخص. مستند OpenAPI همان هفته منتشر می‌شود تا فرانت منتظر شفاهی نماند. کلید تست و کلید تولید جدا هستند. اگر GraphQL انتخاب شود، عمق کوئری را محدود می‌کنیم تا یک کلاینت دیتابیس را خالی نکند.