Перейти к основному содержимому

API Overview

Обзор API платформы Arisweb Marketplace.

Архитектура API​

Платформа использует Supabase как основу для API, предоставляя:

  • REST API для CRUD операций
  • GraphQL для сложных запросов
  • Real-time subscriptions для обновлений в реальном времени
  • Edge Functions для бизнес-логики

Базовые принципы​

RESTful дизайн​

  • Стандартные HTTP методы (GET, POST, PUT, DELETE)
  • Логичная структура URL
  • Статус коды HTTP
  • JSON формат данных

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

Все API запросы требуют аутентификации через JWT токены:

const headers = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json'
};

Мультитенантность​

Все запросы автоматически фильтруются по tenant_id:

// Автоматически добавляется фильтр по tenant
const products = await supabase
  .from('products')
  .select('*'); // RLS автоматически применяет фильтр tenant_id

Основные эндпоинты​

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

  • POST /auth/login - Вход в систему
  • POST /auth/register - Регистрация
  • POST /auth/logout - Выход
  • POST /auth/refresh - Обновление токена

Маркетплейсы​

  • GET /marketplaces - Список маркетплейсов
  • POST /marketplaces - Создание маркетплейса
  • GET /marketplaces/{id} - Детали маркетплейса
  • PUT /marketplaces/{id} - Обновление маркетплейса

Продукты​

  • GET /products - Каталог продуктов
  • POST /products - Добавление продукта
  • GET /products/{id} - Детали продукта
  • PUT /products/{id} - Обновление продукта
  • DELETE /products/{id} - Удаление продукта

Заказы​

  • GET /orders - Список заказов
  • POST /orders - Создание заказа
  • GET /orders/{id} - Детали заказа
  • PUT /orders/{id}/status - Обновление статуса

Фильтрация и поиск​

Стандартные фильтры​

// Фильтрация по категории
const products = await supabase
  .from('products')
  .select('*')
  .eq('category_id', categoryId);

// Поиск по названию
const products = await supabase
  .from('products')
  .select('*')
  .ilike('name', `%${searchTerm}%`);

Семантический поиск​

// Поиск через AI/ML
const searchResults = await supabase.functions.invoke('semantic-search', {
  body: { query: 'красивые летние платья' }
});

Пагинация​

Стандартная пагинация через range:

const { data, count } = await supabase
  .from('products')
  .select('*', { count: 'exact' })
  .range(0, 9); // первые 10 записей

Сортировка​

const products = await supabase
  .from('products')
  .select('*')
  .order('created_at', { ascending: false });

Real-time подписки​

const subscription = supabase
  .channel('products_changes')
  .on('postgres_changes', 
    { 
      event: '*', 
      schema: 'public', 
      table: 'products',
      filter: `tenant_id=eq.${tenantId}`
    }, 
    (payload) => {
      console.log('Product changed:', payload);
    }
  )
  .subscribe();

Обработка ошибок​

Стандартные коды ошибок​

  • 400 - Неверный запрос
  • 401 - Не авторизован
  • 403 - Нет прав доступа
  • 404 - Ресурс не найден
  • 422 - Ошибка валидации
  • 500 - Внутренняя ошибка

Формат ошибок​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Название продукта обязательно",
    "details": {
      "field": "name",
      "value": null
    }
  }
}

Rate Limiting​

Лимиты запросов по ролям:

  • Customer: 100 запросов/минуту
  • Supplier: 500 запросов/минуту
  • Client: 1000 запросов/минуту
  • Admin: 2000 запросов/минуту

Webhook'и​

Для интеграций доступны webhook'и:

  • Создание заказа
  • Изменение статуса оплаты
  • Обновление товара
  • Регистрация пользователя
// Настройка webhook
const webhook = await supabase
  .from('webhooks')
  .insert({
    url: 'https://your-app.com/webhook',
    events: ['order.created', 'payment.completed']
  });

SDK и библиотеки​

JavaScript/TypeScript​

npm install @supabase/supabase-js

Конфигурация клиента​

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
);

Тестирование API​

Postman коллекция​

Доступна готовая коллекция для тестирования API endpoints.

Swagger документация​

Интерактивная документация доступна по адресу: https://your-project.supabase.co/rest/v1/

Лимиты и квоты​

  • Максимальный размер запроса: 1MB
  • Таймаут: 30 секунд
  • Максимальная глубина вложенности: 10 уровней
  • Лимит записей в ответе: 1000 (по умолчанию 100)

Миграции и версионирование​

API поддерживает обратную совместимость:

  • Новые поля добавляются опционально
  • Устаревшие поля помечаются как deprecated
  • Критичные изменения выносятся в новые версии