Skip to content

README_OLD.md

Latest commit

 

History

History
65 lines (54 loc) · 4.22 KB

README_OLD.md

File metadata and controls

65 lines (54 loc) · 4.22 KB
Raw

DevQuiz — документация для фронтенда

Всё, что нужно знать, чтобы подключить фронтенд к DevQuiz API, не заглядывая в код бэкенда.

Содержание

Файл О чём
01-getting-started.md Базовый URL, как устроен запрос, первый вызов, GraphiQL
02-authentication.md Регистрация, вход, токен, защищённые запросы
03-queries.md Все запросы (чтение): параметры, ответы, ошибки
04-mutations.md Все мутации (запись): параметры, ответы, ошибки
05-flows.md Готовые сценарии: пройти квиз, челлендж, профиль
06-errors.md Формат ошибок и полный список сообщений
07-client-setup.md Клиент на fetch, React-хуки, Apollo/urql
08-game-rules.md XP, уровни, стрики, бейджи — формулы
09-cors-and-deploy.md CORS, домены, переменные окружения
schema.graphql Актуальная SDL-схема (для кодогенерации и автодополнения)

Самое главное за 30 секунд

POST  http://127.0.0.1:8000/graphql     ← вообще все данные идут сюда
GET   http://127.0.0.1:8000/health      ← единственный REST, проверка живости

const res = await fetch("http://127.0.0.1:8000/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    // только для защищённых операций:
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    query: `query { topics { id name } }`,
    variables: {},
  }),
});
const { data, errors } = await res.json();

Три вещи, из-за которых чаще всего ломается интеграция:

  1. GraphQL почти всегда отвечает HTTP 200 — даже когда произошла ошибка. Проверять надо не res.ok, а поле errors в теле ответа. Подробнее — 06-errors.md.
  2. Токен передаётся как Authorization: Bearer <token>, без него защищённые операции вернут ошибку Authentication required. Подробнее — 02-authentication.md.
  3. Домен фронтенда нужно прописать в CORS на бэкенде, иначе браузер заблокирует запрос ещё до отправки. Подробнее — 09-cors-and-deploy.md.

Что вообще умеет API

  • Аккаунты — регистрация, вход, JWT на 7 дней.
  • Контент — темы (Python, SQL, Docker...), вопросы с вариантами ответа, подсказки, объяснения.
  • Квизы — выдача N случайных вопросов без правильных ответов, проверка, разбор каждого вопроса после сдачи.
  • Геймификация — XP, уровни (Beginner → Expert), стрики по дням, 10 бейджей.
  • Лидерборды — глобальный по XP и отдельный по каждой теме.
  • Челленджи — квиз по инвайт-коду из 8 символов, общий лидерборд участников.
  • Публичные профили — по нику, со статистикой и бейджами.

Чего нет (осознанно): аватарок и загрузки файлов — для этого нужно объектное хранилище (S3/MinIO), а файловая система контейнера стирается при каждом деплое.