REST Maturity Level 2¶

مقدمه¶

این سیستم بر اساس REST Maturity Level 2 طراحی شده است. درک این مفهوم برای استفاده صحیح از API ضروری است.

سطوح REST (Richardson Maturity Model)¶

سطح 0: The Swamp of POX (HTTP به عنوان تونل)¶

POST /getOrders
POST /createOrder
POST /cancelOrder

مشکلات:

❌ از HTTP فقط به عنوان حمل‌کننده استفاده می‌شود
❌ هیچ مزیتی از REST ندارد
❌ همه چیز از طریق POST انجام می‌شود

سطح 1: Resources (منابع)¶

POST /orders
POST /orders/123

ویژگی‌ها: - ✅ منابع جداگانه داریم

❌ هنوز از HTTP به درستی استفاده نمی‌شود
❌ همه چیز POST است

سطح 2: HTTP Verbs (ما استفاده می‌کنیم)¶

GET    /orders              - لیست سفارشات
POST   /orders              - ایجاد سفارش
GET    /orders/123          - دریافت سفارش
PATCH  /orders/123          - به‌روزرسانی سفارش
DELETE /orders/123          - حذف سفارش

ویژگی‌ها: - ✅ استفاده از متدهای HTTP به درستی

✅ کدهای وضعیت معنادار
✅ قابلیت کش‌ینگ
✅ استاندارد و قابل فهم

سطح 3: Hypermedia Controls (HATEOAS)¶

{
  "orders": [...],
  "_links": {
    "self": { "href": "/orders/123" },
    "cancel": { "href": "/orders/123/cancel" }
  }
}

ویژگی‌ها: - ✅ لینک‌های هدایتگر

❌ پیچیدگی بیشتر
❌ برای این پروژه استفاده نمی‌شود

سیستم ما: سطح 2¶

اصول طراحی¶

1. استفاده از متدهای HTTP¶

# ✅ صحیح
GET    /api/exchange/v1/symbols
POST   /api/exchange/v1/orders
GET    /api/exchange/v1/orders/{uid}
PATCH  /api/exchange/v1/orders/{uid}
DELETE /api/exchange/v1/orders/{uid}

# ❌ اشتباه
POST   /api/exchange/v1/getSymbols
POST   /api/exchange/v1/createOrder
POST   /api/exchange/v1/getOrder
POST   /api/exchange/v1/updateOrder
POST   /api/exchange/v1/deleteOrder

2. کدهای وضعیت معنادار¶

# موفقیت
200 OK - عملیات موفق
201 Created - منبع ایجاد شد
204 No Content - موفق بدون بدنه

# خطای کلاینت
400 Bad Request - درخواست نامعتبر
401 Unauthorized - عدم احراز هویت
403 Forbidden - عدم دسترسی
404 Not Found - یافت نشد
422 Unprocessable - خطای اعتبارسنجی

# خطای سرور
500 Internal Server Error - خطای داخلی
503 Service Unavailable - سرویس در دسترس نیست

3. منابع خوانا¶

# ✅ خوانا و منطقی
/api/exchange/v1/symbols
/api/exchange/v1/orders
/api/exchange/v1/trades

# ❌ غیرخوانا
/api/v1/get_all_symbols
/api/v1/order_management/create
/api/v1/trade_history/get

مثال‌های کامل¶

مثال 1: مدیریت سفارشات¶

درخواست‌ها:

# 1. لیست سفارشات
GET /api/exchange/v1/orders?status=active

# 2. ایجاد سفارش
POST /api/exchange/v1/orders
Body: {"symbol": "BTC-IRR", "side": "buy", ...}

# 3. دریافت سفارش خاص
POST /api/exchange/v1/orders/ord_123

# 4. به‌روزرسانی سفارش
PATCH /api/exchange/v1/orders/ord_123
Body: {"price": "1050000000"}

# 5. لغو سفارش
POST /api/exchange/v1/orders/ord_123/cancel

پاسخ‌ها:

# 1. لیست
200 OK + JSON با heads, items, total

# 2. ایجاد
201 Created + JSON سفارش ایجاد شده

# 3. دریافت
200 OK + JSON سفارش

# 4. به‌روزرسانی
200 OK + JSON سفارش به‌روز شده

# 5. لغو
200 OK + JSON سفارش لغو شده

مثال 2: احراز هویت¶

درخواست‌ها:

# Login
POST /api/auth/v1/login
Body: {"client_id": "...", "client_secret": "..."}

# Refresh
POST /api/auth/v1/refresh
Body: {"refresh_token": "..."}

پاسخ‌ها:

# موفق
200 OK + JSON با access_token و refresh_token

# ناموفق
401 Unauthorized + JSON با توضیح خطا

چرا سطح 2؟¶

✅ مزایا¶

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

پیاده‌سازی در سیستم ما¶

الگوی استاندارد¶

1. لیست‌گیری¶

GET /api/{app}/v1/{resource}?offset=0&limit=10

پاسخ:

{
  "heads": {...},
  "items": [...],
  "total": 100,
  "offset": 0,
  "limit": 10
}

2. ایجاد¶

POST /api/{app}/v1/{resource}
Body: {...}

پاسخ:

{
  "uid": "new_id",
  "created_at": "2025-12-30T10:00:00Z",
  ...
}

3. دریافت¶

POST /api/{app}/v1/{resource}/{uid}

پاسخ:

{
  "uid": "item_id",
  ...
}

4. به‌روزرسانی¶

PATCH /api/{app}/v1/{resource}/{uid}
Body: {"field": "new_value"}

پاسخ:

{
  "uid": "item_id",
  "updated_at": "2025-12-30T10:00:00Z",
  ...
}

5. حذف¶

DELETE /api/{app}/v1/{resource}/{uid}

پاسخ:

{
  "uid": "item_id",
  "updated_at": "2025-12-30T10:00:00Z",
  ...
}

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

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

[ ] از متدهای HTTP صحیح استفاده شده
[ ] کدهای وضعیت معنادار برگردانده می‌شود
[ ] منابع نام‌گذاری خوانا دارند
[ ] پارامترهای query استاندارد هستند
[ ] ساختار پاسخ یکپارچه است

خلاصه¶

REST Maturity Level 2 به معنای:

✅ استفاده از HTTP verbs (GET, POST, PATCH, DELETE)
✅ استفاده از کدهای وضعیت معنادار
✅ منابع خوانا و ساختاریافته
✅ قابلیت کش‌ینگ و استاندارد

این سیستم:

از سطح 2 REST استفاده می‌کند
استاندارد و قابل فهم است
برای اکثر کاربردها کافی است
توسط همه ابزارها پشتیبانی می‌شود

بعدی: مطالعه احراز هویت