طراحی API: قرارداد سیستم با دنیا — طراحی سیستم نرم‌افزاری

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

رستوران به جای API — مشتری از روی منو سفارش می‌دهد؛ آشپزخانه پشت دیوار است. API همان منو و پنجره سفارش است، نه خودِ دیتابیس و دیگ‌ها.

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

REST: پیش‌فرض دنیای وب

REST چیز مرموزی نیست. می‌گوید دنیا را به Resource تقسیم کن — گفتگو، پیام، سفارش — به هر کدام یک URL بده، و کار را با متدهای HTTP بگو. قدرت آن در یکنواختی است: آدم تازه‌وارد بدون سند بلند هم می‌تواند حدس بزند «لیست را چطور بگیرم» و «یکی را چطور حذف کنم».

متد	معنا	Idempotent؟
GET	خواندن منبع؛ نباید چیزی را عوض کند	بله
POST	ساختن چیز تازه، یا شروع یک کار	خیر
PUT	جایگزینی کامل همان منبع	بله
PATCH	ویرایش جزئی	معمولاً خیر
DELETE	حذف	بله

Idempotent یعنی بار دوم همان کار، اثر تازه نسازد. دو بار GET فقط دو بار خواندن است. دو بار POST معمولاً دو سفارش می‌سازد — و همین برای پرداخت خطرناک است.

GET    /v1/chats?cursor=abc&limit=20      لیست گفتگوها
POST   /v1/chats/42/messages               ارسال پیام
GET    /v1/messages/97                     یک پیام
DELETE /v1/messages/97                     حذف پیام

چهار چیزی که تازه‌کارها فراموش می‌کنند

متد و URL فقط پوسته‌اند. بیشتر درد تولید از این چهار تا می‌آید.

Idempotency

تکرار یک درخواست نباید اثر دوباره بگذارد. برای POST حساس مثل پرداخت، کلاینت یک Idempotency-Key می‌فرستد. اگر اینترنت قطع شد و همان درخواست دوباره آمد، سرور نتیجه قبلی را برمی‌گرداند؛ بار دوم پول نمی‌کشد.

Pagination

هرگز «همه» را یک‌جا برنگردان. Offset ساده است ولی در صفحه‌های عمیق کند و گاهی ناسازگار است. Cursor — آخرین آیتمی که دیدی — پایدارتر و سریع‌تر است.

Versioning

قرارداد را بی‌خبر نشکن. فیلد تازهٔ اختیاری معمولاً امن است؛ عوض کردن اسم id به uid کلاینت‌های قدیمی را می‌شکند و یعنی /v2. از روز اول نسخه بگذار.

خطاهای صریح

عدد HTTP درست بفرست، و در بدنه بگو چه شد: یک code قابل‌پردازش، یک message خوانا، و اگر لازم است جزئیات. «یک چیزی خراب شد» به درد کلاینت نمی‌خورد.

وقتی REST تنها ابزار نیست

REST پیش‌فرض خوبی است، نه مذهب. گاهی شکل حرف زدن باید عوض شود. اول مسئله را بگو، بعد ابزار را انتخاب کن.

سبک	بهترین جا	هزینه
GraphQL	چند جور کلاینت که هر کدام برش متفاوتی از داده می‌خواهند	پیچیدگی سرور بیشتر؛ Cache کردن سخت‌تر
gRPC	حرف زدن سرویس با سرویس داخل شبکه خودت؛ سریع و با قرارداد سفت protobuf	برای مرورگر معمولی مناسب نیست
WebSocket	خط دوطرفه زنده: چت، قیمت لحظه‌ای، بازی	باید اتصال‌های باز را نگه داری و مقیاس بدهی
Webhook	خبر دادن به سیستم بیرونی وقتی اتفاقی افتاد — مثلاً «پرداخت شد»	باید retry داشته باشد و امضا شود تا جعلی نیاید

به زبان ساده

API منوی رستوران سیستم توست: بقیه از روی قرارداد مشخص سفارش می‌دهند، نه از داخل آشپزخانه.

مثال واقعی

اپ تاکسی برای ثبت سفر یک فرم استاندارد می‌فرستد؛ اگر اینترنت قطع شد همان Idempotency-Key نمی‌گذارد دو سفر ثبت شود.