API چیست؟
API (Application Programming Interface) به‌سادگی یک قرارداد است که مشخص می‌کند دو نرم‌افزار چگونه با هم صحبت کنند. در دنیای بورس، API کارگزاری به نرم‌افزار شما اجازه می‌دهد بدون نیاز به کلیک دستی، سفارش خرید یا فروش ارسال کنید، موجودی حساب را ببینید، یا قیمت‌های لحظه‌ای را دریافت کنید.
فکر کنید API یک گارسون در رستوران است. شما (کلاینت) منو را می‌بینید، سفارش می‌دهید، و گارسون (API) سفارش را به آشپزخانه (سرور) می‌برد و غذای آماده را به شما برمی‌گرداند. شما نیازی ندارید بدانید آشپزخانه چطور کار می‌کند — فقط باید بدانید چطور سفارش بدهید.
REST API — استاندارد رایج
REST (Representational State Transfer) محبوب‌ترین سبک طراحی API است. در REST، هر منبع (resource) یک URL منحصربه‌فرد دارد و عملیات‌ها با HTTP methods مشخص می‌شوند.
HTTP Methods (افعال HTTP)
| متد | کاربرد | مثال در کارگزاری |
|---|---|---|
GET | دریافت اطلاعات | دریافت قیمت لحظه‌ای نماد |
POST | ایجاد یک منبع جدید | ثبت سفارش خرید |
PUT | به‌روزرسانی کامل | ویرایش کامل سفارش |
PATCH | به‌روزرسانی جزئی | تغییر فقط تعداد سفارش |
DELETE | حذف | لغو سفارش |
Status Codes — کدهای وضعیت HTTP
هر پاسخ API یک کد عددی ۳ رقمی برمی‌گرداند که نشان می‌دهد درخواست چه نتیجه‌ای داشته:
کدهای ۲xx — موفقیت
200 OK— درخواست موفق بود (مثلاً قیمت با موفقیت برگشت).201 Created— منبع جدید ساخته شد (مثلاً سفارش با موفقیت ثبت شد).204 No Content— موفق، بدون محتوای بازگشتی (مثلاً پس از حذف).
کدهای ۴xx — خطای کلاینت (شما)
400 Bad Request— درخواست شما اشتباه است (مثلاً JSON نامعتبر).401 Unauthorized— لاگین نکرده‌اید یا توکن منقضی شده.403 Forbidden— لاگین کرده‌اید ولی اجازه‌ی این عمل را ندارید.404 Not Found— منبع پیدا نشد (مثلاً نماد اشتباه).429 Too Many Requests— محدودیت تعداد درخواست (Rate Limit) — باید کندتر بزنید.
کدهای ۵xx — خطای سرور
500 Internal Server Error— خطای داخلی سرور کارگزاری.502 Bad Gateway— سرور کارگزاری در دسترس نیست.503 Service Unavailable— سرور موقتاً از کار افتاده (مثلاً زمان تعطیلی بازار).
احراز هویت در API
اکثر APIهای کارگزاری نیاز به احراز هویت دارند. روش‌های رایج:
- Bearer Token (JWT): یک توکن بلندمدت در هدر
Authorization: Bearer <token>ارسال می‌شود. - API Key: یک کلید ثابت در هدر
X-API-Key. - OAuth2: جریان چندمرحله‌ای که توکن کوتاه‌مدت می‌دهد — امن‌ترین روش.
- Cookie/Session: مانند لاگین در مرورگر — برای APIهای قدیمی‌تر.
Body و JSON
برای ارسال داده‌ها به API (مثلاً اطلاعات سفارش)، معمولاً از فرمت JSON در بدنه‌ی درخواست استفاده می‌شود. مثال:
POST /api/v1/orders
Content-Type: application/json
Authorization: Bearer eyJhbGc...
{
"symbol": "خودرو",
"side": "buy",
"quantity": 100,
"price": 3500,
"type": "limit"
}Headers — هدرهای مهم
| هدر | توضیح |
|---|---|
Content-Type | نوع داده‌ی بدنه — معمولاً application/json |
Authorization | توکن احراز هویت |
Accept | چه نوع پاسخی قبول می‌کنید |
User-Agent | مشخصات کلاینت — برخی سرورها بر اساس آن فیلتر می‌کنند |
Rate Limiting — محدودیت درخواست
سرورهای API برای جلوگیری از آسیب، تعداد درخواست‌های یک کاربر را محدود می‌کنند. مثلاً:
- نهایتاً ۶۰ درخواست در دقیقه
- نهایتاً ۱۰ درخواست در ثانیه
اگر محدودیت را رعایت نکنید، کد 429 دریافت می‌کنید و سرور موقتاً شما را مسدود می‌کند. ربات‌های حرفه‌ای این محدودیت‌ها را به‌صورت خودکار رعایت می‌کنند.
جمع‌بندی
API زبان مشترک بین نرم‌افزار شما و سرور کارگزاری است. درک REST، HTTP methods، status codes، احراز هویت و محدودیت‌ها، برای هر معامله‌گری که می‌خواهد از ربات استفاده کند ضروری است. ربات سرخطچی تمام این مفاهیم را به‌صورت خودکار مدیریت می‌کند — شما فقط URL، هدرها و بدنه‌ی درخواست را وارد می‌کنید و ربات بقیه را انجام می‌دهد.