Подключение к публичному API события

Границы и аутентификация

Сейчас опубликована одна read-only интеграция Hack API: GET /api/v1/public/event. Токен и сессия личного кабинета не нужны. Регистрация пользователей, команды, organizer/admin endpoints и внутренние feature flags не входят в этот контракт. Публичного контракта developer keys, scopes и webhooks пока нет. Hack API — закрытый продукт; открытая документация не предоставляет лицензию на его исходный код.

Семантика ответа

Ответ — {data: event} либо {data: null}. Сначала сервер выбирает активное событие; если активного нет — ближайшее будущее по времени начала. Когда подходящих событий нет, data равен null. Для интерфейса это «нет события для отображения», а не пустое фиктивное событие или сетевая ошибка. Показывайте event_name как текст, а не непроверенный HTML.

Nullable-даты, сведения о площадке и контакты должны оставаться необязательными в интерфейсе. Флаги регистрации проверяйте как boolean. Публичные флаги описывают доступность регистрации, но не дают права доступа и не заменяют серверную проверку условий участия. Новые неизвестные поля не должны ломать клиента. Полный список и типы — в OpenAPI и справочнике.

Минимальный JavaScript-клиент

Node.js 22+ либо современный браузер с fetch/AbortSignal.timeout:

export async function getPublicEvent(baseUrl = 'https://api.hack-rnd.ru', signal = AbortSignal.timeout(5000)) {
    const response = await fetch(new URL('/api/v1/public/event', baseUrl), {
        headers: { Accept: 'application/json' }, signal, redirect: 'error',
    });
    if (!response.ok) {
        const error = new Error(`Public event request failed: HTTP ${response.status}`);
        error.status = response.status;
        error.retryAfter = response.headers.get('retry-after');
        throw error;
    }
    if (!response.headers.get('content-type')?.includes('application/json')) {
        throw new Error('Expected an application/json response');
    }
    const payload = await response.json();
    if (!payload || !Object.hasOwn(payload, 'data')) throw new Error('Missing public event data');
    if (payload.data === null) return null;
    const event = payload.data;
    if (typeof event !== 'object' || Array.isArray(event)
        || typeof event.id !== 'string' || typeof event.event_name !== 'string'
        || typeof event.participant_registration_open !== 'boolean'
        || typeof event.volunteer_registration_open !== 'boolean') {
        throw new Error('Invalid public event fields');
    }
    return event;
}

Минимальный клиент проверяет только используемые им поля и не заменяет полную schema validation. Отдельная live-проверка хаба сверяет весь ответ с OpenAPI без сохранения данных события. Импортируйте модуль и вызовите getPublicEvent(); в интерфейсе разделяйте null и ошибку запроса. Браузерный вызов также зависит от фактической CORS-политики API. Успешный server-side fetch не доказывает разрешение любого browser origin; при необходимости используйте свой backend, не пересылая приватные cookie кабинета.

Ошибки, ограничения и кэш

• В маршруте задано throttle:120,1. Ключи limiter и инфраструктурные ограничения зависят от окружения; не считайте это отдельной квотой каждого приложения.
• При 429 учитывайте Retry-After, если он есть, и выдерживайте паузу. Не повторяйте запрос немедленно в цикле. Пример возвращает status/header через ошибку, но сам не делает retry.
• При сетевой ошибке, timeout или 5xx показывайте временную недоступность либо последний успешный кэш с явной отметкой устаревания. Не подменяйте флаги регистрации.
• Кэшируйте публичный ответ с подходящим TTL. Обновляйте по контролируемому расписанию, а не на каждое нажатие клавиши.
• Не привязывайтесь к форме JSON-сообщения ошибки: здесь специфицирован успешный payload 200. data:null — корректное успешное состояние.

Границы проверки

2026-10-17: ответ живого публичного endpoint прошёл schema validation. Локальные тесты покрывают null, корректные flags, некорректный flag, отсутствие data, 429 и 503. Это не проверка authenticated journeys, browser CORS, всех инфраструктурных ошибок или живого состояния «нет события». Последний вариант проверен fixture и исходным кодом.