Документация API Квазара

Быстрый старт

Базовый адрес API совпадает с адресом сайта. Все ответы — JSON. Публичные данные (профили, публичные репозитории) доступны без токена. Попробуйте прямо сейчас:

curl https://ваш-домен/api/v1/users/quasar

У каждого ресурса есть и веб-адрес, и API-адрес: страница репозитория /автор/репозиторий, его API — /api/v1/repos/автор/репозиторий.

Токены доступа

Токен заменяет пароль в запросах к API. Создайте его в Настройках → Токены доступа и выберите области доступаобласти доступа — права токена: какие действия разрешено делать от вашего имени:

• repo:read — читать ваши репозитории и файлы
• repo:write — создавать репозитории и записывать файлы
• stars — дарить звёзды от вашего имени
• profile — видеть ваш профиль

Токен показывается один раз при создании — сохраните его сразу. Отозвать можно в любой момент.

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

Передавайте токен в заголовке:

curl -H "Authorization: Bearer qsr_ваш_токен" https://ваш-домен/api/v1/user

Веб-сессии (после входа на сайт) тоже работают — то же API доступно из браузера с cookie сессии.

Пользователи

GET /api/v1/users/{username} — публичный профиль и список публичных репозиториев. Без токена.

curl https://ваш-домен/api/v1/users/quasar

GET /api/v1/user — ваш профиль (по токену). Scope: profile.

Репозитории

GET /api/v1/repos/{owner}/{repo} — метаданные и список файлов. Публичные — без токена, приватные — с токеном владельца (scope repo:read).

GET /api/v1/repos — список ваших репозиториев. Scope: repo:read.

POST /api/v1/repos — создать репозиторий, можно сразу с файлами (scope repo:write):

curl -X POST https://ваш-домен/api/v1/repos \
  -H "Authorization: Bearer qsr_ваш_токен" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Мой проект",
    "description": "Создан через API",
    "language": "Python",
    "topics": ["api", "пример"],
    "files": {
      "README.md": "# Привет!\nСоздано через API Квазара.",
      "src/main.py": "print('Привет, Квазар!')"
    }
  }'

Файлы

GET /api/v1/repos/{owner}/{repo}/files/{путь} — содержимое файла. Текстовые приходят в поле content, файлы из внешних облаков — в поле externalUrl.

curl https://ваш-домен/api/v1/repos/quasar/welcome/files/README.md

Прямая ссылка на файл (для скачивания и встраивания): /f/{owner}/{repo}/{путь}, добавьте ?dl=1 для принудительного скачивания. Архив всего репозитория: /api/download/{owner}/{repo}.

Звёзды (валюта)

Через веб-интерфейс звёзды дарятся кнопками на страницах репозиториев и профилей. Пользователям начисляются: +100 за регистрацию, +10 за дневной бонус (раз в 20 часов), награды за задания новичка, +5 автору за каждый форк его проекта.

Программная передача звёзд доступна с scope stars через веб-API POST /api/stars/gift (подарок автору) — формат: { username, amount, note? }.

Ошибки и лимиты

• 400 — некорректные данные (в поле error — человекочитаемое пояснение на русском)
• 401 — нет/просрочен токен или сессия
• 403 — у токена нет нужной области доступа
• 404 — ресурс не найден или приватный
• 429 — слишком часто: логин и OTP ограничены по времени

Как устроено хранение

Квазар спроектирован так, чтобы рост не съедал сервер: метаданные (пользователи, репозитории, структура файлов, транзакции звёзд) живут в базе SQLite, а «тяжёлое» — во внешних облаках.

• Текстовые файлы кода до 64 КБ — прямо в базе: просмотр мгновенный.
• Файлы больше 64 КБ и бинарники — цепочка внешних хранилищ без регистрации: catbox.moe (200 МБ, бессрочно) → vikingfile.com (гигабайты) → 0x0.st → gofile.io. Первый, кто принял файл, становится его домом.
• Если облака недоступны — аварийный фолбэк в базу (до 6 МБ), сайт продолжает работать.
• В продакшене база живёт в облачном KV платформы: на Vercel это Vercel Blob (каждое значение шифруется AES-256-GCM ключом из переменных окружения), на Netlify — Netlify Blobs; локально — настоящий SQLite-файл data/quasar.db.

Настройка платформы (для владельца)

Все интеграции включаются переменными окружения платформы — в Vercel: Project → Settings → Environment Variables, в Netlify: Site configuration → Environment variables. Код менять не нужно — после сохранения переменных сделайте Redeploy:

Важно про безопасность: сайт работает по HTTPS, пароли хранятся как scrypt-хэши, сессии — httpOnly cookie, токены — только sha256-хэш в базе, а база на Vercel дополнительно зашифрована на стороне приложения. Токены платформ (Vercel/Netlify), использованные при деплое, рекомендуем сменить в настройках аккаунтов.