Какой HTTP-метод будешь использовать в приложении для получения отчетов?

Выбор HTTP-метода для получения отчётов

Для получения отчётов я буду использовать GET, но с оговорками. Это не всегда очевидно — всё зависит от сложности отчёта и параметров фильтрации.

GET vs POST для получения данных

GET — стандартный выбор:

// Простой отчёт
GET /api/v1/reports/sales?period=2024-Q1&department=sales

// Преимущества:
// - Идемпотентный (безопасен для повторных запросов)
// - Кэшируется браузером
// - Параметры в URL (sharen bookmark)
// - Простой дебаг (видно в истории)

POST — когда GET недостаточен:

// Сложный отчёт с множеством критериев
POST /api/v1/reports/custom

// Body:
{
  "metrics": ["revenue", "profit", "roi"],
  "dimensions": ["department", "region", "date"],
  "filters": {
    "dateRange": { "from": "2024-01-01", "to": "2024-03-31" },
    "department": ["sales", "marketing"],
    "minRevenue": 100000
  },
  "sorting": [{ "field": "revenue", "direction": "desc" }],
  "pagination": { "limit": 100, "offset": 0 }
}

Когда использовать GET

1. Простые отчёты с несколькими фильтрами:

// Продажи по месяцам
GET /api/v1/reports/monthly-sales?year=2024&currency=USD

// Активные пользователи
GET /api/v1/reports/active-users?period=7days&status=active

// Продажи по странам
GET /api/v1/reports/sales-by-country?sortBy=revenue

2. Когда нужна кэшируемость:

// GET легко кэшируется
GET /api/v1/reports/quarterly-analytics

// Браузер может кэшировать ответ
Cache-Control: max-age=3600

// CDN может кэшировать

3. Bookmarkable и shareable URL:

GET /api/v1/reports/sales
  ?period=Q1-2024
  &department=Sales
  &region=Europe
  &format=json

// Ты можешь отправить этот URL другому и он увидит тот же отчёт

Когда использовать POST

1. Много фильтров (большой URL):

// Это будет ОЧЕНЬ длинный URL — плохо
GET /api/v1/reports/detailed-sales
  ?months=january,february,march,april,may,june
  &departments=sales,marketing,engineering,hr,finance
  &regions=usa,europe,asia,africa
  &productCategories=cat1,cat2,cat3,cat4,cat5
  &customerTypes=vip,regular,new,inactive
  &metrics=revenue,profit,roi,margin,volume

// Лучше использовать POST с телом

2. Динамические параметры (UI выбрал сложный фильтр):

interface ReportRequest {
  metrics: string[];
  filters: Record<string, any>;
  customCalculations: {
    field: string;
    formula: string;
  }[];
}

const report = await fetch('/api/v1/reports/custom', {
  method: 'POST',
  body: JSON.stringify(reportRequest)
});

3. Сохранение параметров на сервере (saved reports):

// Пользователь создал сложный отчёт и хочет его сохранить
POST /api/v1/reports
{
  "name": "Quarterly Sales Analysis",
  "description": "Detailed breakdown by department and region",
  "config": { /* сложная конфигурация */ }
}

// Ответ: { "id": "report-123" }

// Следующий раз просто загружаем
GET /api/v1/reports/report-123

Лучшие практики для отчётов

1. REST API дизайн:

// Одноразовые отчёты
GET /api/v1/reports/sales
  ?period=2024-Q1
  &format=json

// Сохранённые отчёты
GET /api/v1/reports/{reportId}
GET /api/v1/reports/{reportId}/export?format=csv

// Создание сохранённого отчёта
POST /api/v1/reports

// Обновление
PUT /api/v1/reports/{reportId}

// Удаление
DELETE /api/v1/reports/{reportId}

2. Различные форматы:

// JSON
GET /api/v1/reports/sales.json

// CSV
GET /api/v1/reports/sales.csv

// PDF
GET /api/v1/reports/sales.pdf

// Или через query параметр
GET /api/v1/reports/sales?format=csv

3. Асинхронные отчёты (для больших данных):

// 1. Отправляем запрос на сборку отчёта
POST /api/v1/reports/async
{
  "config": { /* большой отчёт */ }
}
// Ответ: { "taskId": "task-123", "status": "processing" }

// 2. Проверяем статус
GET /api/v1/reports/tasks/task-123
// Ответ: { "status": "completed", "reportId": "report-123" }

// 3. Скачиваем готовый отчёт
GET /api/v1/reports/report-123

4. Пагинация:

GET /api/v1/reports/sales
  ?page=1
  &limit=100
  &offset=0

// Ответ
{
  "data": [ /* 100 строк */ ],
  "total": 5000,
  "page": 1,
  "pages": 50,
  "hasMore": true
}

5. Фильтрация и сортировка:

GET /api/v1/reports/sales
  ?filter[department]=sales&filter[region]=europe
  &sort=-revenue,+date
  &fields=date,department,revenue,profit

Пример фронтенда

interface ReportFilters {
  period?: string;
  department?: string[];
  region?: string[];
  format?: 'json' | 'csv' | 'pdf';
}

async function fetchReport(filters: ReportFilters) {
  const params = new URLSearchParams();
  
  Object.entries(filters).forEach(([key, value]) => {
    if (Array.isArray(value)) {
      value.forEach(v => params.append(key, v));
    } else if (value) {
      params.set(key, value);
    }
  });

  const response = await fetch(`/api/v1/reports/sales?${params}`);
  
  if (filters.format === 'csv') {
    // Скачиваем файл
    const blob = await response.blob();
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'report.csv';
    a.click();
  } else {
    // Показываем в UI
    const data = await response.json();
    return data;
  }
}

Итоговые рекомендации

1. GET — для простых, cacheable отчётов
2. POST — для сложных фильтров или асинхронных операций
3. Используй query параметры если URL остаётся разумного размера (< 2000 символов)
4. Переходи на POST если много фильтров
5. Сохраняй конфигурации отчётов (saved reports) — удобнее для пользователей
6. Поддерживай разные форматы (JSON, CSV, PDF)
7. Используй асинхронные отчёты для больших датасетов