قراردادها و کانوانشن‌های API

مقدمه

این سند قراردادهای استاندارد API را توضیح می‌دهد. رعایت این قراردادها باعث یکپارچگی، قابلیت نگهداری و تجربه توسعه‌دهنده بهتر می‌شود.

ساختار URL

فرمت کلی

{base_url}/api/{app}/v1/{resource}[/{item_id}][/{action}]

توضیحات

• {base_url}: آدرس سرور (مثلاً https://p2p.icepbn.ir)

• api: پیشوند ثابت برای تمامی APIها

• {app}: نام سرویس/اپلیکیشن

• sso: مدیریت کاربران

• accounting: مدیریت مالی

• exchange: بازار معاملاتی

• v1: نسخه API (همیشه v1 در این مستندات)

• {resource}: نام ریسورس (مثلاً users, orders, trades)

• {item_id}: شناسه آیتم خاص (اختیاری)

• {action}: عملیات خاص (مثلاً cancel, deposit)

مثال‌ها

GET  /api/auth/v1/login
POST /api/user/v1/users
GET  /api/user/v1/users/{user_id}
POST /api/exchange/v1/orders/{order_id}/cancel
GET  /api/accounting/v1/wallets/{wallet_id}/transactions

متدهای HTTP

استفاده استاندارد

متد	کاربرد	کد وضعیت موفق	توضیحات
GET	دریافت لیست یا آیتم	200	برای خواندن داده‌ها
POST	ایجاد یا بازیابی	201/200	برای ایجاد یا retrieve
PATCH	به‌روزرسانی جزئی	200	برای تغییر فیلدهای خاص
DELETE	حذف	200	برای حذف آیتم

کدهای وضعیت HTTP

موفقیت (2xx)

• 200 OK: عملیات موفق (بدون ایجاد منبع)

• 201 Created: منبع جدید ایجاد شد

• 204 No Content: عملیات موفق بدون بدنه پاسخ

خطای کلاینت (4xx)

• 400 Bad Request: درخواست نامعتبر

• 401 Unauthorized: عدم احراز هویت

• 403 Forbidden: عدم دسترسی (احراز شده اما مجاز نیست)

• 404 Not Found: منبع یافت نشد

• 409 Conflict: تعارض (مثلاً داده تکراری)

• 422 Unprocessable Entity: داده نامعتبر

• 429 Too Many Requests: محدودیت نرخ درخواست

خطای سرور (5xx)

• 500 Internal Server Error: خطای داخلی

• 502 Bad Gateway: مشکل در سرویس وابسته

• 503 Service Unavailable: سرویس در دسترس نیست

• 504 Gateway Timeout: زمان انتظار به پایان رسیده

ساختار پاسخ

پاسخ استاندارد لیست

{
  "heads": {
    "id": {
      "en": "Id"
    },
    "uid": {
      "en": "Uid"
    },
    "created_at": {
      "en": "Created At"
    },
    "updated_at": {
      "en": "Updated At"
    },
    "is_deleted": {
      "en": "Is Deleted"
    },
    "meta_data": {
      "en": "Meta Data"
    },
    "user_id": {
      "en": "User Id"
    },
    ...
  },
  "items": [
    {
        "uid": "01995196-ef5e-7239-87b9-e93d61004317",
        "created_at": "2025-09-16T08:14:53.306000",
        "updated_at": "2025-09-16T08:14:53.306000",
        "is_deleted": false,
        "meta_data": null,
        ...
    }
  ],
  "total": 100,
  "offset": 0,
  "limit": 10
}

پاسخ استاندارد تکی

{
  "uid": "01995196-ef5e-7239-87b9-e93d61004317",
  "created_at": "2025-09-16T08:14:53.306000",
  "updated_at": "2025-09-16T08:14:53.306000",
  "is_deleted": false,
  "meta_data": null,
  "user_id": "admin",
  ...
}

پاسخ خطا

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "توضیح خطا",
      "type": "error_type",
      "ctx": {
        "limit_value": 100
      }
    }
  ]
}

پارامترهای درخواست

Query Parameters (برای GET)

# مثال
GET /api/exchange/v1/orders?user_id=user_123&status=active&offset=0&limit=10

پارامترهای مشترک: - offset: شروع صفحه‌بندی (پیش‌فرض: 0)

• limit: حداکثر تعداد (پیش‌فرض: 10، حداکثر: 100)

• created_at_from: فیلتر تاریخ شروع

• created_at_to: فیلتر تاریخ پایان

Path Parameters

# مثال
GET /api/sso/v1/users/user_123
POST /api/exchange/v1/orders/order_456/cancel

Body Parameters (برای POST/PATCH)

# مثال
curl -X POST "{BASE_URL}/api/sso/v1/users" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "[email protected]"
  }'

فرمت داده‌ها

تاریخ و زمان

فرمت: ISO 8601

2025-12-30T10:00:00Z
2025-12-30T10:00:00+03:30

اعداد

فرمت: String برای مقادیر مالی

{
  "price": "1000000000",
  "quantity": "0.5",
  "fee": "50000"
}

دلیل: جلوگیری از مشکلات دقت اعشار در جاوااسکریپت و سایر زبان‌ها

مقادیر بولین

{
  "is_active": true,
  "is_deleted": false
}

آرایه‌ها

{
  "tags": ["tag1", "tag2"],
  "rejection_reasons": ["insufficient_balance", "price_too_low"]
}

نام‌گذاری

نام فیلدها

استفاده از snake_case:

{
  "user_id": "user_123",
  "wallet_id": "wallet_456",
  "created_at": "2025-12-30T10:00:00Z",
  "is_active": true
}

نام ریسورس‌ها

جمع‌بندی کوتاه و معنادار: - users (نه user_list)

• orders (نه order_list)

• trades (не trade_list)

نام اندپوینت‌ها

افعال کوتاه و واضح: - login (نه authenticate)

• refresh (نه refresh_token)

• cancel (نه cancel_order)

صفحه‌بندی (Pagination)

پارامترها

GET /api/exchange/v1/orders?offset=20&limit=10

پاسخ

{
  "heads": {
    "uid": "شناسه",
    "created_at": "تاریخ ایجاد"
  },
  "items": [
    {
      "uid": "order_21",
      "symbol": "BTC-IRR",
      "side": "buy"
    },
    {
      "uid": "order_22",
      "symbol": "ETH-IRR",
      "side": "sell"
    }
  ],
  "total": 100,
  "offset": 20,
  "limit": 10
}

محاسبه صفحه بعدی

# صفحه 1: offset=0, limit=10
# صفحه 2: offset=10, limit=10
# صفحه 3: offset=20, limit=10

offset = (page - 1) * limit

فیلترینگ

انواع فیلترها

1. فیلتر مساوی

GET /api/sso/v1/users?status=active

2. فیلتر تاریخ

GET /api/exchange/v1/orders?created_at_from=2025-12-01T00:00:00Z&created_at_to=2025-12-31T23:59:59Z

3. فیلتر چندگانه

GET /api/exchange/v1/orders?user_id=user_123&status=active&side=buy

نکات امنیتی

1. همیشه از HTTPS استفاده کنید

# ✅ صحیح
https://p2p.icepbn.ir/api/...

# ❌ اشتباه
https://p2p.icepbn.ir/api/...

2. توکن در URL ندهید

# ❌ اشتباه
GET /api/sso/v1/users?token=eyJhbGc...

# ✅ صحیح
GET /api/sso/v1/users
Authorization: Bearer eyJhbGc...

3. داده‌های حساس در لاگ ندهید

# ❌ اشتباه
log("Token: " + token)

# ✅ صحیح
log("Request to /api/v1/users")

مدیریت خطاها

ساختار خطای استاندارد

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "توضیح خطا",
      "type": "error_type"
    }
  ]
}

انواع خطاها

خطای اعتبارسنجی

{
  "detail": [
    {
      "loc": ["body", "price"],
      "msg": "value is less than minimum",
      "type": "value_error.number.not_ge",
      "ctx": {"limit_value": 0}
    }
  ]
}

خطای دسترسی

{
  "detail": "Access denied"
}

خطای منبع یافت نشد

{
  "detail": "User not found"
}

یکپارچگی

تمامی APIها باید:

1. از BASE_URL استفاده کنند

2. از ساختار پاسخ استاندارد پیروی کنند

3. کدهای وضعیت HTTP صحیح برگردانند

4. احراز هویت را پیاده‌سازی کنند

5. صفحه‌بندی را پشتیبانی کنند

چک‌لیست توسعه

قبل از انتشار API:

• [ ] از BASE_URL استفاده شده

• [ ] ساختار پاسخ استاندارد رعایت شده

• [ ] کدهای وضعیت HTTP صحیح هستند

• [ ] احراز هویت پیاده‌سازی شده

• [ ] صفحه‌بندی کار می‌کند

• [ ] نمونه‌های موفق و ناموفق تست شده

• [ ] مستندات به‌روز شده

---

بعدی: مطالعه Pagination و جستجو