API چیست و چگونه بین نرم‌افزارها ارتباط برقرار می‌کند؟

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

رابط برنامه‌نویسی کاربردی (Application Programming Interface یا API) همان لایه است: مجموعه‌ای از قواعد و قابلیت‌ها که یک برنامه در اختیار برنامهٔ دیگر می‌گذارد، نه در اختیار انسان از طریق دکمه و فرم. MDN آن را قرارداد ساده بین نرم‌افزار عرضه‌کننده و مصرف‌کننده می‌داند؛ IBM آن را قواعد یا پروتکل‌هایی می‌نامد که برنامه‌ها داده و قابلیت رد و بدل کنند؛ AWS «رابط» را قرارداد خدمت بین دو کاربرد می‌خواند.

این متن API را از استعاره تا مثال فروشگاه، انواع دسترسی، مستند، نسخه‌بندی و احراز هویت سطح‌بالا جلو می‌برد. هدف این نیست که یک سبک (مثلاً REST) را «تنها راه درست» معرفی کند؛ هدف این است که بتوانید بپرسید قرارداد چیست، چه کسی مسئول خطاست، و چه تغییری کلاینت را می‌شکند.

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

پاسخ کوتاه

API قرارداد صحبت نرم‌افزار با نرم‌افزار است. یک طرف درخواست می‌فرستد (کلاینت)، طرف دیگر پاسخ می‌دهد (سرور). شکل درخواست، دادهٔ مجاز، خطا و محدودیت باید از قبل نوشته شده باشد؛ وگرنه «اتصال» فقط امید است.

1. کاربر با UI کار می‌کند؛ برنامه با API.
2. API فقط داده و عمل لازم را افشا می‌کند، نه کل سیستم داخلی.
3. مستند همان دفترچهٔ قرارداد است: نشانی، روش، ورودی، خروجی، احراز هویت.
4. نسخه مشخص می‌کند کدام کلاینت‌ها بعد از تغییر زنده می‌مانند.
5. احراز هویت می‌گوید درخواست از کیست؛ مجوز می‌گوید اجازهٔ چه کاری دارد — این دو یکی نیستند.

AWS مثال هواشناسی را می‌آورد: سامانهٔ ادارهٔ هوا داده دارد؛ اپ گوشی از طریق API همان داده را می‌گیرد و نمایش می‌دهد. IBM پرداخت شخص‌ثالث را مثال می‌زند: کلیک «پرداخت» یک درخواست به سامانهٔ بیرونی است، نه باز کردن انبار مالی فروشگاه. استعارهٔ گارسون هم همین منطق را دارد، اگر زیاد کش نیاید: مشتری منو را می‌بیند، آشپزخانه را نه؛ گارسون سفارش را با شکل معلوم می‌برد و جواب را برمی‌گرداند.

API خوب سیستم را باز نمی‌کند؛ یک پنجرهٔ کنترل‌شده باز می‌کند.

API دقیقاً چیست — و چه چیزی نیست

MDN تعریف را از رابط کاربری انسان جدا می‌کند: API مجموعهٔ قابلیت و قاعده داخل یک برنامه است که تعامل از راه نرم‌افزار را ممکن می‌کند. در وب، این قابلیت‌ها معمولاً متد، ویژگی، رویداد یا URL هستند. مرورگر API داخلی دارد (موقعیت مکانی، دوربین، انیمیشن)؛ سرویس بیرونی هم API دارد (نقشه، پرداخت، انبار).

سه اشتباه رایج معنی را خراب می‌کند. اول: «API یعنی REST». REST یک سبک معماری است، نه خودِ API؛ مقالهٔ ۰۳۷ این تمایز را باز می‌کند. دوم: «API یعنی JSON». JSON فقط یک قالب رایج بدنه است؛ مقالهٔ ۰۳۸ آن را جدا شرح می‌دهد. سوم: «API یعنی وب‌سرویس». IBM صریح است: هر وب‌سرویس یک API است، ولی هر API وب‌سرویس نیست. کتابخانهٔ سیستم‌عامل هم API دارد؛ فقط روی HTTP سفر نمی‌کند.

آنچه API را مفید می‌کند پنهان‌کاری کنترل‌شده است. IBM می‌نویسد سرور مجبور نیست کل داده را افشا کند؛ بسته‌های کوچک مرتبط با همان درخواست کافی است و جزئیات داخلی پنهان می‌ماند. این هم امنیت است، هم آزادی تغییر پشت قرارداد. اگر فردا جدول انبار عوض شود ولی شکل پاسخ ثابت بماند، ویترین فروشگاه نباید بشکند.

درخواست و پاسخ: مدل کار

IBM و AWS هر دو معماری را با کلاینت و سرور توضیح می‌دهند. برنامه‌ای که درخواست می‌فرستد کلاینت است؛ برنامه‌ای که پاسخ می‌دهد سرور. API پل بین این دو است. کاربر معمولاً این تبادل را نمی‌بیند؛ فقط نتیجه را در صفحه می‌بیند.

در API وب، درخواست اغلب روی HTTP می‌رود. IBM اجزای رایج را چنین می‌چیند: شناسهٔ یکنواخت منبع (URI)، فعل درخواست، سرآیندها، و گاهی بدنه. سرور پاسخ را با داده یا پیام خطا برمی‌گرداند. AWS تأکید می‌کند مستند API باید بگوید این درخواست و پاسخ را چطور بسازید؛ وگرنه قرارداد نانوشته است.

نقطهٔ پایانی (Endpoint) جایی است که تماس واقعاً فرود می‌آید: یک URL مشخص به‌علاوهٔ یک عمل. AWS دو دلیل برای اهمیت endpoint می‌آورد: امنیت — چون سطح حمله است — و کارایی — چون نقطهٔ پرترافیک گلوگاه می‌شود. پایش endpoint بخشی از کار عملیاتی است، نه تزئین.

مثال فروشگاه: فرانت‌اند با API موجودی حرف می‌زند

یک فروشگاه آنلاین را در نظر بگیرید. صفحهٔ محصول باید نام، قیمت و موجودی را نشان دهد. پایگاه موجودی پشت دیوار است: طرح جدول، قفل ردیف، قوانین رزرو. فرانت‌اند نباید مستقیم به آن وصل شود. به‌جای آن یک API موجودی قرارداد می‌گذارد.

کلاینت می‌پرسد: «کالای ۱۲۴ موجود است؟» API پاسخ می‌دهد: شناسه، تعداد قابل‌فروش، و شاید زمان به‌روزرسانی. کلاینت نمی‌پرسد «کدام انبار، کدام قفسه». اگر دو انبار دارید، ادغام پشت قرارداد می‌ماند. اگر موجودی رزرو موقت دارید، منطق رزرو هم پشت همان پنجره است.

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

همین الگو در پرداخت IBM هم دیده می‌شود: صفحه محصول به سامانهٔ پرداخت بیرونی درخواست می‌فرستد، پاسخ را می‌گیرد، و کاربر یک جریان یکدست می‌بیند. UI و API دو سطح‌اند. اگر موجودی در UI تازه به نظر برسد ولی API کهنه باشد، مشکل قرارداد یا کش است، نه «رنگ دکمه».

برای مدیر محصول، سؤال مفید این است: کدام عمل‌ها باید از UI به API ترجمه شوند، و کدام هرگز نباید از بیرون دیده شوند؟ حذف فیزیکی رکورد انبار معمولاً عمل داخلی است. «اتمام موجودی» یک وضعیت قابل‌نمایش است. این مرز را قبل از تخمین اسپرینت بکشید.

انواع API از نظر دسترسی و کاربرد

IBM و AWS API را هم از نظر کاربرد و هم از نظر دامنهٔ دسترسی طبقه‌بندی می‌کنند. این برچسب‌ها جایگزین طراحی نیستند؛ کمک می‌کنند مسئولیت و ریسک را entitle کنید.

API وب و APIهای غیرشبکه‌ای

IBM می‌گوید امروز بیشتر APIها API وب‌اند: انتقال داده و قابلیت روی اینترنت با HTTP. AWS وب API را رابط بین سرور وب و مرورگر/کلاینت وب می‌نامد و یادآوری می‌کند اصطلاح «API جاوا» یا «API سرویس» قدیمی‌تر از وب است. API سیستم‌عامل یا درایور دستگاه هم API است؛ فقط الگوی استقرارش فرق دارد.

عمومی، شریک، داخلی، ترکیبی

هر دو منبع چهار دامنهٔ رایج را تکرار می‌کنند. API باز یا عمومی برای مصرف بیرونی است؛ ممکن است رایگان یا پولی باشد و معمولاً endpoint و قالب مشخص دارد. API شریک برای شرکای تجاری است؛ اغلب از درگاه توسعه‌دهنده و اعتبارنامه می‌گذرد. API داخلی فقط داخل سازمان دیده می‌شود و برای اتصال تیم‌هاست. API ترکیبی چند منبع را در یک تماس جمع می‌کند — مفید وقتی یک کار به چند سرویس نیاز دارد، خطرناک اگر خطاها قاطی شوند.

تصمیم دامنه همان تصمیم ریسک است. API عمومی را بدون سقف نرخ و هویت رها نکنید. API داخلی را «چون داخلی است» بدون مستند نگذارید؛ تیم مجاور همان کلاینت خارجی فرداست. API شریک را با خروج شریک نسخه کنید، نه با تماس تلفنی.

قرارداد: مستند، شکل پیام، و مسئولیت خطا

AWS رابط را قرارداد خدمت می‌داند: چگونه با درخواست و پاسخ حرف بزنند. IBM مستند را دفترچهٔ فنی می‌خواند — پروتکل، زبان، روش احراز هویت، و نحوهٔ کار با سرویس. بدون این دفترچه، «API داریم» یعنی «یک URL در چت گذاشته‌ایم».

یک قرارداد حداقل باید این‌ها را قفل کند: هویت منبع (URI)، فعل مجاز، قالب بدنه، کد وضعیت معنی‌دار، و مثال واقعی. Microsoft در راهنمای طراحی API وب روی استقلال سکو و جفت‌شدگی سست تأکید می‌کند: کلاینت نباید پیاده‌سازی داخلی را بشناسد؛ قالب تبادل باید توافق‌شده باشد. اگر هر تغییر جدول یک فیلد را در پاسخ عوض کند، قرارداد ندارید؛ نشت طرح دارید.

خطا بخش قرارداد است، نه پیوست شرم‌آور. کلاینت باید بفهمد درخواست بد بوده، هویت ناقص بوده، منبع نیست، یا سرور گیر کرده. مقالهٔ ۰۲۲ کدهای HTTP را از این زاویه باز می‌کند. پیام خطای مبهم («خطا رخ داد») هزینهٔ پشتیبانی را به دوش محصول می‌اندازد.

نسخه‌بندی: وقتی قرارداد باید عوض شود

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

چند الگوی رایج در همان راهنما آمده است. نسخه‌بندی در URI مثل ‎/v2/customers ساده و قابل‌کَش است، ولی پیوندها را شلوغ می‌کند. نسخه در query ظاهر منبع را ثابت نگه می‌دارد، اما به تجزیهٔ پارامتر وابسته است. نسخه در سرآیند یا نوع رسانه از نظر معنا تمیزتر است و با پیوندهای hypermedia سازگارتر، ولی کش و پروکسی را سخت‌تر می‌کند. «بدون نسخه» فقط وقتی امن است که افزودن فیلد نادیده‌گرفتنی باشد؛ حذف یا تغییر معنا شکست است.

قانون عملی برای محصول: تغییر سازگار را در همان نسخه منتشر کنید؛ تغییر شکننده را نسخه کنید و تاریخ بازنشستگی بگویید. اگر نمی‌توانید بگویید چند کلاینت روی v1 مانده‌اند، هنوز سیاست نسخه ندارید.

احراز هویت سطح‌بالا: کلید، توکن، درگاه

AWS دو راه رایج امن‌سازی REST API را جدا می‌کند. توکن احراز هویت بررسی می‌کند صداکننده همان کسی است که ادعا می‌کند و برای آن تماس حق دسترسی دارد — مثل ورود به ایمیل. کلید API برنامه را شناسایی می‌کند و برای پایش مصرف مناسب است؛ AWS می‌گوید به اندازهٔ توکن امن نیست، ولی برای دیدن الگوهای استفاده به کار می‌آید.

IBM اضافه می‌کند تماس API معمولاً به اعتبارنامه نیاز دارد و سرآیند HTTP، کوکی یا query می‌تواند لایهٔ بیشتری بدهد. درگاه API (API Gateway) دسترسی را متمرکز می‌کند. AWS درگاه را ابزار مدیریت می‌داند: احراز هویت، آمار، محدودیت نرخ برای تماس‌های مشترک. این‌ها جای طراحی مجوز داخل دامنه را نمی‌گیرند.

تمایز مهم برای تصمیم: احراز هویت (Authentication) می‌گوید «کی هستی»؛ مجوز (Authorization) می‌گوید «چه کار می‌توانی بکنی». قاطی کردن این دو باعث می‌شود کلید API را با نقش انباردار یکی بگیرند. جزئیات این مرز در مقالهٔ ۰۴۶ است. اینجا فقط این را قفل کنید: هر endpoint عمومی بدون هویت و سقف، سطح حمله است.

برای فروشگاه: خواندن موجودی عمومی شاید با کلید برنامه کافی باشد؛ کاهش موجودی یا صدور فاکتور به هویت کاربر یا سرویس معتمد نیاز دارد.

سبک‌ها و پروتکل‌ها — فقط برای انتخاب، نه پرستش

IBM فهرست SOAP، RPC، gRPC، WebSocket، REST و GraphQL را می‌آورد و می‌گوید REST و GraphQL ذاتاً برتر نیستند. AWS REST را رایج‌ترین API وب می‌نامد — نه «همیشه درست». اگر منبع پایدار و کش مهم است، REST کم‌اصطکاک است؛ اگر فرانت دقیقاً فیلد می‌خواهد، GraphQL؛ اگر سرویس داخلی کم‌تأخیر است، gRPC؛ اگر جریان دوطرفه است، WebSocket. اول عمل‌ها را فهرست کنید، بعد سبک را.

یکپارچگی و چرخهٔ ساخت — کوتاه

AWS یکپارچگی API را همگام‌سازی خودکار داده بین کلاینت و سرور می‌داند. IBM فایده را در همکاری و باز کردن قابلیت بدون افشای کل سیستم می‌بیند — به شرط مستند، نسخه و هویت. موجودی و قیمت معمولاً هویت کسب‌وکارند و پشت API خودتان می‌مانند؛ پرداخت یا نقشه اغلب خریدنی‌اند.

AWS پنج گام می‌شمارد: برنامه‌ریزی (مثلاً با OpenAPI)، ساخت نمونه، آزمون، مستند، معرفی. Microsoft هم قرارداد-اول را در برابر پیاده‌سازی-اول می‌گذارد. یک صفحهٔ شروع که در ده دقیقه اولین تماس موفق را بسازد، از مستند تولیدشدهٔ مرده مفیدتر است. «در Postman ۲۰۰» جایگزین آزمون سقف نرخ و خطای کسب‌وکار نیست.

نشانه‌های قرارداد سالم — و وقتی باید توقف کنید

• سالم: یک غریبه با مستند عمومی می‌تواند یک خواندن موفق انجام دهد.
• سالم: تغییر داخلی جدول، فیلد پاسخ را بی‌خبر عوض نمی‌کند.
• سالم: خطا کد دارد، نه فقط متن شاعرانه.
• توقف: کلاینت‌ها از روی شنود ترافیک حدس می‌زنند فیلد یعنی چه.
• توقف: یک کلید مشترک برای خواندن عمومی و عمل مالی.
• توقف: نسخه نیست و هر هفته فیلد حذف می‌شود.

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

جمع‌بندی

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

قدم بعدی کوچک: یک عمل واقعی محصول را روی کاغذ به «درخواست / پاسخ / خطا / چه کسی مجاز است» ترجمه کنید. اگر نتوانستید، هنوز API ندارید؛ فقط یک اتصال موقت دارید.

برای شکل منبع‌محور روی HTTP، ۰۳۷ را بخوانید. برای قالب بدنه، ۰۳۸. برای مرز هویت و مجوز، ۰۴۶. اگر پاسخ‌ها را نمی‌فهمید، ۰۲۲ را کنار میز بگذارید.

منابع و مراجع

• MDN Web Docs — Glossary: API: https://developer.mozilla.org/en-US/docs/Glossary/API
• IBM Think — What is an API (application programming interface)؟: https://www.ibm.com/think/topics/api
• Amazon Web Services — What is an API؟: https://aws.amazon.com/what-is/api/
• Microsoft Learn / Azure Architecture Center — Web API design best practices: https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design

اگر می‌خواهید بعد از تعریف قرارداد، سبک تبادل و قالب پیام را جدا انتخاب کنید، از REST و JSON شروع کنید — نه از خرید ابزار.