ИИ для API разработки

📐 Архитектура API маркетплейса зоотоваров:

6 ресурсов, 28 эндпоинтов:

Products (8): CRUD + поиск + фильтры + изображения + отзывы
Categories (4): CRUD + дерево (parent_id)
Cart (4): добавить/удалить/обновить количество/получить
Orders (6): создать/статус/история/отмена/webhook платежа/трекинг
Sellers (3): профиль/товары продавца/статистика
Reviews (3): создать/список по товару/модерация

Ключевые решения:
• Поиск: `GET /products?q=корм+для+собак&category=dry-food&price_min=500&sort=rating`
• Корзина: server-side (для авторизованных), привязка к userId
• Заказ: state machine (created → paid → shipped → delivered → completed)
• Мультитенантность: sellerId в products, изоляция данных
• Изображения: presigned URL для S3, до 10 на товар

Начинаю с Products — сгенерировать OpenAPI и модели?

📋 OpenAPI + SQL для Products и Categories:

SQL-миграции:
CREATE TABLE categories (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(100) NOT NULL,
slug VARCHAR(100) UNIQUE NOT NULL,
parent_id UUID REFERENCES categories(id),
sort_order INT DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_categories_parent ON categories(parent_id);

CREATE TABLE products (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
seller_id UUID NOT NULL REFERENCES sellers(id),
category_id UUID NOT NULL REFERENCES categories(id),
title VARCHAR(200) NOT NULL,
slug VARCHAR(200) UNIQUE NOT NULL,
description TEXT,
price DECIMAL(10,2) NOT NULL CHECK (price > 0),
stock INT NOT NULL DEFAULT 0 CHECK (stock >= 0),
rating DECIMAL(2,1) DEFAULT 0,
review_count INT DEFAULT 0,
images JSONB DEFAULT '[]'::jsonb,
is_published BOOLEAN DEFAULT false,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_products_category ON products(category_id);
CREATE INDEX idx_products_seller ON products(seller_id);
CREATE INDEX idx_products_search ON products USING gin(to_tsvector('russian', title || ' ' || description));

OpenAPI-спека для Products: 180 строк, 5 эндпоинтов, модели CreateProduct, UpdateProduct, ProductResponse, ProductList с пагинацией.

📋 План документирования 60 эндпоинтов:

Структура документации:
1. Quick Start Guide — первый запрос за 5 минут
2. Аутентификация — получение API-ключа, OAuth2 flow
3. Справочник эндпоинтов — по модулям
4. Модели данных — все schemas
5. Коды ошибок — единая таблица
6. Rate limits и квоты
7. Webhooks — форматы, подпись, retry policy
8. Changelog — версии и breaking changes

Формат для каждого эндпоинта:
• Описание (что делает, когда использовать)
• Параметры (тип, обязательность, ограничения)
• Пример запроса (curl + JavaScript + Python)
• Пример ответа (200 + ошибки)
• Примечания (подводные камни, лимиты)

Скидывайте контроллеры — начну генерировать. По 10-15 эндпоинтов за сессию.

📋 Документация Payments API — 8 эндпоинтов:

POST /api/v1/payments
Создание платежа. Инициирует транзакцию в платёжной системе.

Параметры:
• `amount` (number, required) — сумма в копейках. Минимум: 100 (1 ₽)
• `currency` (string, default: "RUB") — ISO 4217
• `description` (string, max 256) — назначение платежа
• `metadata` (object, optional) — произвольные данные (до 10 ключей)
• `return_url` (string, required) — URL редиректа после оплаты

Пример (curl):
curl -X POST https://api.example.com/api/v1/payments \
-H "Authorization: Bearer sk_live_..." \
-d '{"amount": 150000, "currency": "RUB", "description": "Заказ #1234", "return_url": "https://shop.ru/success"}'

Ответ 201:
{"id": "pay_abc123", "status": "pending", "payment_url": "https://pay.example.com/...", "expires_at": "2026-04-05T12:30:00Z"}

Ошибки: 400 (невалидная сумма), 401 (невалидный ключ), 429 (лимит превышен)

⚠️ Подводный камень: `amount` в копейках, не в рублях. 150000 = 1 500 ₽.

... ещё 7 эндпоинтов задокументированы аналогично.

📐 План рефакторинга legacy API:

Фаза 1 — Аудит (1 день):
Категоризация всех 40 эндпоинтов:
• RPC-стиль (глаголы): 15 штук — `/getUser`, `/createOrder`, `/deleteComment`
• REST-ish: 18 штук — близко к REST, но непоследовательно
• Нормальные: 7 штук — уже в правильном формате

Фаза 2 — Новый стандарт:
• URL: `/api/v2/{resource}` (множественное число, kebab-case)
• Методы: GET/POST/PATCH/DELETE (не PUT)
• Ответы: `{ data: {...}, meta: {...} }` (единый конверт)
• Ошибки: RFC 7807 `{ type, title, status, detail }`
• Пагинация: cursor-based, заголовок Link
• Фильтры: `?filter[status]=active&sort=-created_at`

Фаза 3 — Миграция (2-3 недели):
1. Создать v2 эндпоинты параллельно с v1
2. v1 проксирует на v2 (adapter pattern)
3. Мобильное приложение обновляется на v2
4. v1 помечается deprecated (Sunset header)
5. Через 3 месяца — удаление v1

Маппинг: `/getUser?id=5` → `GET /api/v2/users/5`
`/api/orders/create` → `POST /api/v2/orders`
`/deleteComment?id=5` → `DELETE /api/v2/comments/5`

Начать с маппинга всех 40 эндпоинтов?

🔄 Adapter pattern для обратной совместимости (Express):

// legacy-adapter.js — проксирует v1 → v2

// Маппинг старых URL на новые
const legacyRoutes = {
'GET /getUser': 'GET /api/v2/users/:id',
'POST /createOrder': 'POST /api/v2/orders',
'GET /deleteComment': 'DELETE /api/v2/comments/:id',
'GET /v2/product-list':'GET /api/v2/products',
};

// Middleware: перехватывает старые URL
app.use((req, res, next) => {
const key = `${req.method} ${req.path}`;
if (legacyRoutes[key]) {
// Логируем deprecated usage
logger.warn(`Legacy API call: ${key}`);
// Устанавливаем Sunset header
res.set('Sunset', '2026-10-01');
res.set('Deprecation', 'true');
// Трансформируем запрос
req.url = transformUrl(key, req.query);
req.method = legacyRoutes[key].split(' ')[0];
}
next();
});

Трансформация ответов: v2 формат `{data, meta}` → v1 плоский формат. Всё в одном middleware, v2 контроллеры не знают про v1.

Мониторинг: дашборд deprecated-вызовов. Когда счётчик = 0 → безопасно удалять v1.