Перейти к содержанию

Справочник API Saga

Аудитория: разработчики Последнее обновление: 2025-11-17 Краткое описание: Полная документация REST API платформы Saga — 102 endpoints для пользовательских операций, административного управления, blockchain взаимодействий и системных утилит.

Обзор API

Base URL: https://app.saga.surf (production) | http://localhost:8080 (development)

Версия API: v1 (текущая)

Протоколы: REST (HTTP/HTTPS), WebSocket (запланировано в Phase 3)

Формат ответов: JSON

Аутентификация:

  • User API: JWT (подпись Web3 кошелька)
  • Admin API: JWT (админские credentials)
  • Public API: Аутентификация не требуется

Категории Endpoints

Пользовательские Endpoints (~40 endpoints)

Аутентификация и Аккаунт:

  • POST /api/auth/wallet/connect - Web3 wallet аутентификация
  • POST /api/auth/cookie/verify - Проверка JWT cookie
  • GET /api/user/profile - Получить профиль пользователя

Баланс и Транзакции:

  • GET /api/user/balance - Получить текущий баланс USDC
  • GET /api/user/transactions - Список истории транзакций
  • GET /api/user/transactions/:id - Получить детали транзакции

Инвестиции:

  • POST /api/user/investments - Создать новую инвестицию
  • GET /api/user/investments - Список всех инвестиций
  • GET /api/user/investments/:id - Получить детали инвестиции
  • PUT /api/user/investments/:id - Обновить стратегию инвестиции
  • DELETE /api/user/investments/:id - Отменить инвестицию

Выводы:

  • POST /api/user/withdrawals - Запрос на вывод средств
  • GET /api/user/withdrawals - Список запросов на вывод
  • GET /api/user/withdrawals/:id - Получить статус вывода

Стратегии:

  • GET /api/user/strategies - Список доступных стратегий
  • GET /api/user/strategies/:id - Получить детали стратегии
  • GET /api/user/strategies/:id/performance - Историческая доходность

См.: Документация User API

Административные Endpoints (~40 endpoints)

Админская Аутентификация:

  • POST /api/admin/auth/login - Вход администратора
  • POST /api/admin/auth/refresh - Обновить admin token
  • GET /api/admin/auth/verify - Проверить админскую сессию

Управление Пользователями:

  • GET /api/admin/users - Список всех пользователей
  • GET /api/admin/users/:id - Получить детали пользователя
  • PUT /api/admin/users/:id - Обновить статус пользователя
  • DELETE /api/admin/users/:id - Деактивировать пользователя

Управление Инвестициями:

  • GET /api/admin/investments - Список всех инвестиций
  • GET /api/admin/investments/pending - Ожидающие одобрения
  • PUT /api/admin/investments/:id/approve - Одобрить инвестицию
  • PUT /api/admin/investments/:id/reject - Отклонить инвестицию

Управление Выводами:

  • GET /api/admin/withdrawals - Список всех выводов
  • GET /api/admin/withdrawals/pending - Ожидающие выводы
  • PUT /api/admin/withdrawals/:id/approve - Одобрить вывод
  • PUT /api/admin/withdrawals/:id/execute - Выполнить вывод

Dashboard и Отчетность:

  • GET /api/admin/dashboard/stats - Статистика платформы
  • GET /api/admin/dashboard/revenue - Метрики доходности
  • GET /api/admin/reports/users - Отчет по росту пользователей
  • GET /api/admin/reports/investments - Отчет по инвестициям

См.: Документация Admin API

Публичные/Служебные Endpoints (~22 endpoints)

Здоровье и Статус:

  • GET /health - Проверка здоровья системы
  • GET /api/ping - Проверка доступности API
  • GET /api/version - Информация о версии API
  • GET /api/blockchain/status - Статус blockchain ноды

Faucet (Разработка):

  • POST /api/faucet/request - Запросить тестовые USDC
  • GET /api/faucet/status - Конфигурация faucet
  • GET /api/faucet/balance - Баланс faucet контракта

SLA Мониторинг:

  • GET /api/sla/metrics - SLA метрики
  • GET /api/sla/uptime - Статистика uptime

Blockchain Операции:

  • POST /api/blockchain/rpc - Blockchain RPC proxy
  • GET /api/blockchain/contracts - Информация о развернутых контрактах

См.: Документация Public API

Аутентификация

Пользовательская Аутентификация (Web3)

Процесс:

1. Пользователь подключает MetaMask
2. Frontend запрашивает signature challenge
3. Пользователь подписывает сообщение приватным ключом
4. Backend проверяет подпись
5. Выдает JWT токен (срок действия 24ч)

Пример:

// Frontend
const message = await fetchChallenge(walletAddress);
const signature = await signer.signMessage(message);
const jwt = await authenticate(walletAddress, signature);

// Сохранение JWT
localStorage.setItem('saga_auth_token', jwt);

Заголовки:

Authorization: Bearer <jwt_token>

См.: Руководство по Аутентификации для полного процесса.

Администраторская Аутентификация (JWT)

Процесс:

1. Администратор предоставляет email/password
2. Backend проверяет credentials
3. Выдает admin JWT (админские claims)
4. Админские операции требуют admin роль

Пример:

curl -X POST https://app.saga.surf/api/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@saga-test.com",
    "password": "secure-password"
  }'

Ответ:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 86400,
  "adminClaims": {
    "email": "admin@saga-test.com",
    "roles": ["admin"],
    "permissions": ["*"]
  }
}

Формат Запроса/Ответа

Стандартный Запрос

POST /api/user/investments HTTP/1.1
Host: app.saga.surf
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "strategyId": "balanced-10",
  "amount": "1000.00",
  "currency": "USDC"
}

Стандартный Успешный Ответ

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "data": {
    "investmentId": "inv_123abc",
    "strategyId": "balanced-10",
    "amount": "1000.00",
    "currency": "USDC",
    "apy": 10.0,
    "status": "active",
    "createdAt": "2025-10-03T12:00:00Z"
  },
  "timestamp": "2025-10-03T12:00:01Z"
}

Стандартный Ответ с Ошибкой

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Сумма инвестиции должна быть минимум 10 USDC",
    "details": {
      "field": "amount",
      "provided": "5.00",
      "minimum": "10.00"
    }
  },
  "timestamp": "2025-10-03T12:00:01Z"
}

См.: Руководство по Обработке Ошибок для всех кодов ошибок.

Конвенции API

Именование

Endpoints:

  • Существительные, множественное число: /api/user/investments (не /api/user/investment)
  • Через дефис: /api/admin/withdrawal-requests
  • Resource IDs: /api/user/investments/:investmentId

Query Параметры:

  • camelCase: ?sortBy=createdAt&orderBy=desc
  • Pagination: ?page=1&limit=20
  • Filtering: ?status=active&strategy=balanced

Поля Ответа:

  • camelCase: { "investmentId": "...", "createdAt": "..." }
  • ISO 8601 даты: "2025-10-03T12:00:00Z"
  • SafeDecimal суммы: "1000.50" (string для точности)

HTTP Методы

  • GET - Операции чтения (idempotent)
  • POST - Операции создания (non-idempotent)
  • PUT - Операции обновления (idempotent)
  • PATCH - Частичное обновление (idempotent)
  • DELETE - Операции удаления (idempotent)

Idempotency:

  • GET, PUT, PATCH, DELETE - безопасно повторять
  • POST - используйте idempotency keys для критичных операций: 
    {
  "idempotencyKey": "uuid-123-abc",
  "amount": "1000.00"
}

Пагинация

Запрос:

GET /api/user/transactions?page=2&limit=50

Ответ:

{
  "success": true,
  "data": [ /* 50 транзакций */ ],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 523,
    "totalPages": 11,
    "hasNext": true,
    "hasPrevious": true
  }
}

По умолчанию:

  • page: 1
  • limit: 20 (максимум: 100)

Фильтрация и Сортировка

Фильтрация:

GET /api/admin/users?status=active&strategy=aggressive&minBalance=1000

Сортировка:

GET /api/user/transactions?sortBy=createdAt&orderBy=desc

Комбинирование:

GET /api/admin/investments?status=pending&sortBy=amount&orderBy=desc&page=1&limit=20

Тестирование и Примеры

Примеры cURL

Баланс Пользователя:

curl -X GET https://app.saga.surf/api/user/balance \
  -H "Authorization: Bearer $JWT_TOKEN"

Создание Инвестиции:

curl -X POST https://app.saga.surf/api/user/investments \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "strategyId": "balanced-10",
    "amount": "1000.00"
  }'

Админ: Список Ожидающих Выводов:

curl -X GET https://app.saga.surf/api/admin/withdrawals/pending \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN"

См.: директорию ./examples/ для большего количества примеров.

Примеры SDK (TypeScript)

import { SagaClient } from '@saga/sdk';

// Инициализация
const client = new SagaClient({
  baseUrl: 'https://app.saga.surf',
  jwt: localStorage.getItem('saga_auth_token')
});

// Пользовательские операции
const balance = await client.user.getBalance();
const investment = await client.user.createInvestment({
  strategyId: 'balanced-10',
  amount: '1000.00'
});

// Админские операции
const adminClient = new SagaAdminClient({ jwt: adminJwt });
const pendingWithdrawals = await adminClient.withdrawals.getPending();

См.: Integration-Only Architecture - Enterprise API integration approach

Ограничение Запросов (Rate Limiting)

Лимиты:

  • User API: 1000 запросов/час на пользователя
  • Admin API: 10000 запросов/час на админа
  • Public API: 100 запросов/час на IP
  • Faucet: 10 запросов/день на адрес

Заголовки:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1696348800

Превышение:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Слишком много запросов. Попробуйте через 1 час."
  }
}

Детальная Документация API

Детальная User API

📚 Полный Справочник User API:

Детальная Admin API

📚 Полный Справочник Admin API:

Детальная Public API

📚 Полный Справочник Public API:

🛠️ Инструменты и Ресурсы

Swagger UI (Интерактивная Документация)

URL: https://app.saga.surf/swagger/index.html (скоро)

Возможности:

  • Тестирование endpoints прямо из браузера
  • Автогенерация из Go code annotations
  • Real-time примеры запросов/ответов

Postman Коллекция

Скоро: Загружаемая Postman коллекция для всех endpoints.

Генерация:

make generate-postman-collection

Лучшие Практики Безопасности

Безопасность JWT Токенов

✅ Делайте:

  • Храните JWT в httpOnly cookies (frontend)
  • Используйте HTTPS только в production
  • Реализуйте token refresh (перед истечением)
  • Валидируйте JWT подпись на сервере

❌ Не делайте:

  • Не храните JWT в localStorage (риск XSS)
  • Не делитесь JWT токенами
  • Не используйте одинаковый JWT для user + admin
  • Не игнорируйте время истечения

Безопасность API Key (Будущее)

Phase 3: API ключи для third-party интеграций

Лучшие Практики:

  • Ротация ключей ежеквартально
  • Используйте environment variables (никогда не hardcode)
  • Ограничивайте permissions на ключ
  • Мониторьте usage логи

📞 Поддержка и Вопросы

По вопросам API:

  • Telegram: @AiSeeQ для поддержки по API
  • GitHub: Создайте issue с тегом api
  • Email: api@saga.surf

Частые Проблемы:

Версионирование API

Текущая Версия: v1

Стратегия Версионирования:

  • Мажорные изменения: /api/v2/... (breaking changes)
  • Минорные обновления: Обратно совместимые (без изменения версии)
  • Deprecation: Уведомление за 6 месяцев до удаления

Связанная Документация

Руководства для Разработчиков:

Архитектура:

Бизнес:

✍️ Информация о Документе

📋 Метаданные

Версия: 2.6.268

Обновлено: 2025-10-21

Статус: Published