testube — справочник для фронтенда

Всё, что нужно, чтобы написать клиент: адреса, формы запросов и ответов, правила доступа и грабли, на которые здесь легко наступить.

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

JWT в заголовке: Authorization: Bearer <access_token>. Access-токен живёт expires_in секунд (по умолчанию час), после чего меняется на новый через /auth/refresh — заново спрашивать пароль не нужно.

МетодПутьТелоОтвет
POST/auth/register{username, email, password}201 TokenResponse
POST/auth/login{email, password}200 TokenResponse
POST/auth/google{id_token, username?}200 TokenResponse
POST/auth/refresh{refresh_token}200 TokenResponse
POST/auth/logout{refresh_token}204
POST/auth/logout-all— (токен)204
GET/auth/me—200 User

Ещё несколько ручек работают кодом из письма — сброс пароля, подтверждение адреса, вход по коду, смена адреса. Общие правила и первые три — ниже, в «Кодах из писем»; смена адреса — в «Смене email», рядом с личными данными.

// TokenResponse
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "7TXspv4MCFitf_Z1MOvBNbF8xXlEsKE7UPJFKYkPaXs",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "...",
    "username": "neo",
    "display_name": "Нео",
    "email": "neo@example.com",
    "email_verified": false,
    "avatar_url": null,
    "created_at": "2026-09-06T10:00:00Z"
  }
}

Refresh-токен одноразовый. Каждый обмен выдаёт новую пару и гасит предъявленный токен; храните только последний. Если предъявить уже потраченный, вся цепочка обновлений этой сессии гасится целиком и приходит 401 — это защита от повторного использования украденного токена, а не ошибка клиента. Практический вывод: не обновляйте токен из двух вкладок одновременно, иначе вторая уронит сессию обеим. Живёт refresh-токен 30 суток (JWT__REFRESH_TTL_SECS).

/auth/logout гасит одну сессию и не требует access-токена: выйти нужно уметь и с протухшим. /auth/logout-all гасит все сессии пользователя.

Ограничения: username — 3–32 символа латиницы, цифр, _ и -; пароль — 8–128 символов. Email приводится к нижнему регистру.

/auth/register принимает ещё три необязательных поля — first_name, last_name, phone — с теми же правилами, что у PATCH /me/profile (см. «Личные данные»); null и отсутствие поля значат «не указано». В TokenResponse их нет: читать их — GET /me/profile. username — это ещё и адрес канала (@username в ссылке), а display_name — показываемое имя: его правят через PATCH /me/channel, и ссылки при этом не ломаются.

/auth/login не уточняет, что именно неверно — email или пароль: иначе эндпоинт превращается в оракул для перебора зарегистрированных адресов. Показывайте пользователю общее «неверный email или пароль».

email_verified в User — подтверждён ли адрес кодом из письма (см. «Подтверждение адреса»). У аккаунтов, заведённых до появления кодов, он false. Подтверждением считается и любой другой верно введённый код, пришедший на этот адрес: сброса пароля или входа по коду.

Коды из писем

Сброс пароля, подтверждение адреса, вход по коду и смена адреса устроены одинаково: API шлёт на почту пятизначный код, клиент возвращает его в следующем запросе. Общие правила:

Почта может быть выключена. Если на сервере не настроена отправка писем (MAIL__TRANSPORT=none, так по умолчанию), каждая ручка, которая шлёт код, отвечает 503 с текстом в error: код не придёт, ждать его незачем. Показывайте этот текст и предлагайте вход по паролю. Ручки, которые код только проверяют, работают как обычно.

Телефона и SMS нет: коды приходят только на почту. Вкладка «Telefon raqam» на экранах сброса и входа по коду пока ничего не отправляет.

Восстановление пароля

Три шага, экраны «Parolni tiklash» → «Kodni kiriting» → «Yangi parol yarating».

POST /auth/password-reset
{"email": "aziz@example.com"}
-> 202 (тело пустое)

POST /auth/password-reset/verify
{"email": "aziz@example.com", "code": "04217"}
-> 200 {"reset_token": "...", "expires_in": 600}
-> 400 {"error": "..."}   неверный, просроченный или сожжённый код

POST /auth/password-reset/confirm
{"reset_token": "...", "password": "новый пароль"}
-> 200 TokenResponse
-> 400 {"error": "..."}   короткий пароль или негодный reset_token

Подтверждение адреса

POST /auth/email/verify/request      (токен)
-> 202 (тело пустое)
-> 409 {"error": "..."}   адрес уже подтверждён

POST /auth/email/verify              (токен)
{"code": "04217"}
-> 200 User               (с "email_verified": true)
-> 400 {"error": "..."}   неверный, просроченный или сожжённый код

Что значит неподтверждённый адрес — решение продукта, пока такое:

Оба пункта можно пересмотреть; когда это случится, об изменении будет сказано здесь.

Вход по коду

Экран «OTP orqali kirish», затем «Kodni kiriting».

POST /auth/otp/request
{"email": "aziz@example.com"}
-> 202 (тело пустое)

POST /auth/otp/verify
{"email": "aziz@example.com", "code": "04217"}
-> 200 TokenResponse
-> 401 {"error": "..."}   неверный, просроченный или сожжённый код

Вход через Google

Клиент получает ID-токен Google сам (в браузере через Google Identity Services, с тем же client id, что настроен на сервере) и меняет его на нашу пару токенов:

POST /auth/google
{"id_token": "eyJ...", "username": "aziz"}

API проверяет подпись токена ключами Google, iss (accounts.google.com), aud (наш client id), срок действия и email_verified: true. Затем ищет аккаунт:

  1. уже привязанный к этому аккаунту Google (по его постоянному sub);
  2. иначе с тем же email (без учёта регистра), но только если у аккаунта email_verified: true: такой аккаунт привязывается к Google, его пароль продолжает работать. Если адрес у аккаунта не подтверждён, приходит 409 и привязки нет: иначе тот, кто первым зарегистрировал чужой адрес с паролем, делил бы аккаунт с владельцем адреса. Пользователю нужно войти паролем и подтвердить адрес (или сбросить пароль кодом из письма), после чего вход через Google сработает;
  3. иначе создаёт новый. Для него нужен username по правилам регистрации (это адрес канала, потом его не сменить); display_name берётся из имени в Google, email из токена. Пароля у такого аккаунта нет: /auth/login отвечает ему тем же 401, что и на неверный пароль, а завести пароль можно сбросом пароля по коду из письма.

Созданный или привязанный через Google аккаунт получает email_verified: true: адрес подтвердил Google.

username читается только в третьем случае; в первых двух его можно не слать. Каждый вход начинает новую сессию, как /auth/login.

ОтветКогда
200TokenResponse: вход в найденный аккаунт или в только что созданный
400username не проходит правила регистрации
401токен испорчен, просрочен, выписан для другого client id или email не подтверждён
409аккаунта нет, а username не прислан или занят (тело ниже)
409аккаунт с этим email уже привязан к другому аккаунту Google (только error)
409аккаунт с этим email есть, но адрес не подтверждён (только error)
503вход через Google не настроен на сервере или ключи Google недоступны
// 409: нужно имя пользователя
{
  "error": "аккаунта ещё нет: выберите имя пользователя",
  "suggested_username": "aziz"
}

suggested_username выведен из email и свободен на момент ответа. Покажите то же поле имени, что на форме регистрации, с этим значением, и повторите запрос с тем же id_token и выбранным username. ID-токен Google живёт час, так что повтор укладывается.

Запрос считается в лимит /auth/*. Сервер включает вход, когда задан GOOGLE__CLIENT_ID (client id OAuth из Google Cloud; через запятую, если клиентов несколько, например веб и мобильное приложение). Без него ручка отвечает 503, и кнопку стоит прятать или объяснять, что вход недоступен.

Идентификаторы

У видео короткий публичный идентификатор — 11 символов алфавита A-Za-z0-9_-, как в ссылках YouTube (dQw4w9WgXcQ). Именно он приходит в поле id и подставляется во все пути:

/videos/dQw4w9WgXcQ
/videos/dQw4w9WgXcQ/playback
/videos/dQw4w9WgXcQ/hls/master.m3u8

Внутренний UUID наружу не выходит вовсе. Идентификатор непрозрачен: не разбирайте его и не пытайтесь по нему что-то вычислить.

Где видео упоминается внутри другой модели (Comment.video_id, Playlist.cover_video_id, Notification.video_id), там тоже публичный id, и /videos/{video_id} по нему открывается.

Остальные сущности — пользователи, каналы, комментарии, плейлисты, уведомления — адресуются UUID. Канал вдобавок доступен по имени: /channels/by-username/neo. Строка неверного формата в пути видео даёт 404, а не 400: API не подсказывает, какие идентификаторы бывают.

Ошибки

Тело всегда одинаковое: {"error": "человекочитаемый текст"}.

КодКогда
400не прошла валидация, битый курсор, подписка на себя
401нет токена, токен просрочен или испорчен
403доступ есть, но действие чужое (правка чужого видео)
404нет объекта — или он есть, но скрыт (см. ниже)
409состояние не позволяет: файл не загружен, видео не готово
413загруженный файл больше лимита (/complete, см. «Загрузка»)
422тело не разобралось (не тот тип поля, неизвестный enum)
429превышен лимит частоты, см. заголовок Retry-After
500внутренняя ошибка; подробности только в логах сервера
503на сервере выключена почта, а ручка шлёт код (см. «Коды…»)
503вход через Google не настроен или ключи Google недоступны

404 вместо 403 для приватного. Чужое приватное видео отвечает 404, как будто его не существует. Это намеренно: иначе по кодам ответов можно перебором узнать, какие идентификаторы заняты. Не показывайте пользователю «нет доступа» там, где пришёл 404.

Ограничение частоты

Общий лимит — 20 запросов в секунду с всплеском до 40, на /auth/* строже: 10 в минуту. При отказе приходит 429 и Retry-After в секундах.

Клиенту стоит уважать Retry-After и не ретраить вслепую: параллельные вкладки складываются в один счётчик.

По чему считается общий лимит:

Лимит /auth/* всегда считается по IP-адресу, даже если токен есть.

IP-адрес клиента — это адрес соединения. За обратным прокси, чья сеть указана в RATE_LIMIT__TRUSTED_PROXIES, адресом считается самый правый элемент X-Forwarded-For, который сам не входит в доверенные сети. От остальных соединений заголовок игнорируется, поэтому подставить в него чужой адрес бесполезно. Серверный код (например, Next.js), который ходит в API от имени зрителя без его токена, делит один счётчик на всех, если только он не приходит из доверенной сети и не передаёт адрес зрителя в X-Forwarded-For.

Пагинация

Два разных механизма — не перепутайте.

Курсорная (/videos, /videos/my, /feed, /channels/{id}/videos, /me/history, /notifications, комментарии). Параметры ?limit= (1–100, по умолчанию 20) и ?cursor=.

{ "items": [/* ... */], "next_cursor": "dHwyMDI2LTA5LTA2VDEwOjAwOjAwWnw..." }

Следующая страница — тот же запрос с cursor=next_cursor. next_cursor: null означает, что данные кончились. Курсор непрозрачен: не разбирайте его и не конструируйте сами.

Внутри курсора спрятаны две разные формы пагинации. Хронологические сортировки листаются по ключу «время + id», ранжированные (sort=trending, sort=most_viewed, sort=top у комментариев) — по смещению: keyset-пагинация требует стабильного полного порядка, а ранг не уникален и меняется вместе с данными. Снаружи разницы нет, но курсор нельзя переносить между сортировками: смена sort без сброса cursor даёт 400. Меняете сортировку — начинайте список заново. Курсор помнит сортировку, под которой выдан, поэтому 400 придёт и при переходе между сортировками одного вида (newest → oldest). У /videos/my курсор помнит и sort, и order. /me/watch-later листается по третьему ключу, порядку, который задал сам зритель (см. «Смотреть позже и понравившееся»); курсор другого вида там тоже 400.

Offset-овая (/videos/search, /subscriptions, /playlists, /playlists/{id}/items, /me/reports). Параметры ?limit= и ?offset=, в ответе они же:

{ "items": [/* ... */], "limit": 20, "offset": 0 }

Модели

type VideoStatus = "uploading" | "processing" | "ready" | "failed";
type VideoKind = "regular" | "short" | "live";
type VideoCategory =
  // словарь закрыт, см. «Категория»
  | "music"
  | "podcasts"
  | "news"
  | "nature"
  | "animation"
  | "gaming"
  | "education"
  | "sports"
  | "entertainment";
type FailureReason = "unsupported_format" | "corrupt" | "no_video_stream" | "internal";
type Visibility = "public" | "unlisted" | "private";
type Reaction = "like" | "dislike";
type FeedSort = "newest" | "oldest" | "trending" | "most_viewed";
type CommentSort = "newest" | "top";

interface ChannelSummary {
  // всё, что нужно строке под заголовком
  id: string; // UUID автора, он же id канала
  username: string;
  display_name: string;
  avatar_url: string | null;
  subscriber_count: number;
}

interface Video {
  id: string; // 11 символов, короткая ссылка
  channel: ChannelSummary; // канал едет вместе с видео, второй запрос не нужен
  title: string;
  description: string | null;
  location: string | null; // место съёмки, до 100 символов; null, если не указано
  category: VideoCategory | null; // одна категория или null; название берите из каталогов клиента
  status: VideoStatus;
  kind: VideoKind; // чем видео является; со статусом не связано
  visibility: Visibility;
  duration_secs: number | null; // появляется после транскодинга
  thumbnail_url: string | null; // путь этого же API; владельцу приватного — подписан
  hls_url: string | null; // null, пока видео не транскодировано
  view_count: number;
  like_count: number;
  dislike_count: number;
  comment_count: number;
  tags: string[]; // до 15 штук, нижний регистр
  published_at: string | null; // когда стало видно; null — не публиковалось
  created_at: string; // RFC 3339
  updated_at: string;
  // Только владельцу: в GET /videos/{id} своего видео, GET /videos/my и в
  // ответах на свои POST/PATCH. У всех остальных этих ключей нет вовсе.
  failure_reason?: FailureReason | null; // непусто только при status = failed
  source_filename?: string | null; // имя файла из POST /videos, без пути
}

// Только GET /videos/{id}: карточка плюс то, что касается этого зрителя.
// В лентах, поиске, списках и ответах на POST/PATCH этих ключей нет.
interface VideoDetail extends Video {
  in_watch_later: boolean | null; // в «Смотреть позже» зрителя; null без токена
  captions: CaptionTrack[]; // всегда есть; [] — субтитров нет, см. «Субтитры»
}

interface CaptionTrack {
  lang: string; // тег BCP 47: "uz", "uz-Cyrl", "ru", "en"; в <track srclang>
  label: string; // подпись в меню: присланная автором или самоназвание языка
  url: string; // путь этого API, как thumbnail_url; владельцу приватного — подписан
  kind: "subtitles"; // других видов пока нет
  auto: false; // распознавания речи нет, дорожки загружает автор
}

interface Comment {
  id: string;
  video_id: string; // публичный id видео (11 символов), как Video.id
  author_id: string;
  author_username: string;
  author_display_name: string;
  author_avatar_url: string | null;
  parent_id: string | null; // на что ответили: корень или ответ; null — сам корень
  body: string;
  like_count: number;
  dislike_count: number; // публичный, как и like_count
  reply_count: number; // прямые ответы; есть и у ответов, у второго уровня всегда 0
  my_reaction: Reaction | null; // null для анонима и для того, кто не голосовал
  liked_by_me: boolean | null; // my_reaction === "like"; null для анонима
  edited_at: string | null; // непусто → показать «изменено»
  created_at: string;
  updated_at: string;
}

interface ChannelLink {
  label: string;
  display: string;
  url: string;
  icon_url: string | null; // значок сайта: путь этого API или null, см. «Значки ссылок»
}

interface Channel {
  id: string;
  username: string; // адрес канала: @username
  display_name: string;
  description: string; // короткая строка карточки
  about: string | null; // длинный текст вкладки «о канале»
  avatar_url: string | null; // путь этого API после загрузки, см. «Аватар и баннер»
  banner_url: string | null;
  country: string | null; // ISO 3166-1 alpha-2, всегда в верхнем регистре
  links: ChannelLink[];
  created_at: string;
  subscriber_count: number;
  video_count: number; // только публичные готовые видео
  view_count: number; // суммарно по всем публичным видео канала
  subscribed: boolean | null; // null для анонима
  notifications_enabled: boolean | null; // колокольчик; null, если подписки нет
}

interface Playlist {
  id: string;
  owner_id: string;
  owner_username: string;
  owner_display_name: string;
  owner_avatar_url: string | null;
  title: string;
  description: string | null;
  visibility: Visibility;
  video_count: number;
  cover_video_id: string | null; // первое видео плейлиста — обложка карточки
  cover_thumbnail_url: string | null; // превью обложки; своё приватное — подписано
  created_at: string;
  updated_at: string;
}

interface WatchProgress {
  position_secs: number; // где остановились
  watched_secs: number; // суммарно просмотрено
  completed: boolean;
  last_watched_at: string;
}

type NotificationKind = "new_video" | "comment_reply" | "video_comment";

interface Notification {
  id: string;
  kind: NotificationKind;
  actor_id: string;
  actor_username: string;
  actor_display_name: string;
  actor_avatar_url: string | null;
  video_id: string | null; // короткий id, если событие про видео
  video_title: string | null;
  comment_id: string | null;
  read: boolean;
  created_at: string;
}

type ReportReason =
  "spam" | "sexual" | "violence" | "hate" | "harassment" | "misinformation" | "copyright" | "other";

interface Report {
  id: string;
  video_id: string;
  reason: ReportReason;
  details: string | null;
  status: "pending" | "reviewed" | "dismissed";
  created_at: string;
}

Формулировку уведомления («X выложил Y») собирает клиент: она зависит от языка, а API отдаёт только kind, автора и заголовок видео.

Жизненный цикл видео: uploading → (подтверждение загрузки) → processing → (воркер) → ready, либо failed, если транскодинг не удался. Пока статус не ready, hls_url и thumbnail_url пустые (кроме случая, когда владелец уже загрузил своё превью, см. «Выбор превью»), а видео не попадает ни в ленту, ни в поиск.

Видео

МетодПутьДоступОписание
POST/videosтокенСоздать запись, получить ссылку для загрузки
POST/videos/{id}/completeвладелецПодтвердить загрузку
POST/videos/{id}/upload-urlвладелецНовая ссылка для загрузки
POST/videos/{id}/multipartвладелецНачать загрузку частями
GET/videos/{id}/multipartвладелецКакие части уже легли
POST/videos/{id}/multipart/partsвладелецПодписать части
POST/videos/{id}/multipart/completeвладелецСобрать файл и подтвердить
DELETE/videos/{id}/multipartвладелецОтменить загрузку частями
POST/videos/{id}/retranscodeвладелецПерегнать исходник заново
GET/videosвсеЛента: public + ready, курсор
GET/videos/search?q=всеПоиск, offset; фильтры, см. «Поиск»
GET/videos/search/suggest?q=всеПодсказки: список строк
GET/videos?kind=всеЛента одного рода: short, live
GET/videos?category=всеЛента одной категории
GET/categoriesвсеСловарь категорий, см. «Категория»
GET/videos/myтокенСвои видео: фильтры студии, курсор
GET/videos/my/countsтокенСчётчики вкладок студии
GET/videos/{id}по видимостиКарточка (VideoDetail)
PATCH/videos/{id}владелецПравка метаданных
DELETE/videos/{id}владелецУдалить запись и файлы
GET/videos/{id}/playbackпо видимостиКак воспроизводить
POST/videos/{id}/viewвсеЗасчитать просмотр
POST/videos/{id}/shareвсеЗаписать репост
GET/videos/{id}/relatedпо видимостиПохожие видео (до 20), ?for=viewer
GET/videos/{id}/thumbnailпо видимостиПревью (картинка); подпись заменяет токен
GET/videos/{id}/thumbnailsвладелецВарианты превью и какой выбран
GET/videos/{id}/thumbnails/{t}владелецОдин вариант (картинка); подпись заменяет токен
POST/videos/{id}/thumbnail/uploadвладелецСсылка для загрузки своей картинки
POST/videos/{id}/thumbnail/completeвладелецПроверить картинку и выбрать её
GET/videos/{id}/hls/{path}по видимостиМанифест и сегменты
GET/videos/{id}/captions/{lang}.vttпо видимостиФайл субтитров (WebVTT); подпись заменяет токен
POST/videos/{id}/captions/{lang}владелецСсылка для загрузки дорожки субтитров
POST/videos/{id}/captions/{lang}/completeвладелецПроверить .vtt и опубликовать дорожку
DELETE/videos/{id}/captions/{lang}владелецСнять дорожку субтитров
GET/feed/mixesвсеПолка миксов для главной, до 20

Лента: сортировка и категории

GET /videos?sort=trending&category=music&limit=20

sort — newest (по умолчанию), oldest, most_viewed, trending. «В тренде» — просмотры, поделённые на возраст: без деления подборка навсегда застревала бы на старых роликах с большим счётчиком.

category фильтрует ленту по одной категории из словаря: это и есть чипы категорий над ней и страница /music (см. «Категория»). Неизвестный слаг отвечает 400, пустой category= значит «без фильтра».

tag фильтрует ленту по одному свободному тегу, который набрал автор. Для чипов он больше не нужен: тег ничем не ограничен, и чип, отправленный как тег, находил только то, что автор случайно так назвал. Теги хранятся в нижнем регистре, так что фильтр регистронезависим только если вы шлёте их уже нормализованными.

kind сужает ленту до одного рода видео при любой sort, см. «Род видео». Все фильтры складываются через «И»: ?category=music&kind=short отдаёт музыкальные шортсы.

Смена sort требует сбросить cursor (см. «Пагинация»).

Похожие и «для вас»

GET /videos/{id}/related отдаёт до 20 видимых видео, кроме самого {id}: сначала по пересечению тегов с играющим видео, потом свежие. Ответ — голый массив карточек Video, без конверта items / next_cursor.

GET /videos/{id}/related?for=viewer — та же колонка, ранжированная для зрителя (чип «Siz uchun»). Форма ответа, лимит, правила видимости и лимит запросов те же.

Другое значение for — 400.

Полка миксов

Дизайн главной ставит в сетку видео карточку микса: обложка со стопкой листов, бейдж «Miks» вместо длительности и одна строка каналов вместо автора. GET /videos её не отдаёт и не будет: превратить элементы ленты в объединение «видео или микс» значило бы сломать каждого клиента, который уже рисует их как видео. Поэтому миксы отдельный ресурс, а в сетку их вставляет клиент.

GET /feed/mixes?limit=4 открыт всем, токен необязателен:

{
  "items": [
    {
      "id": "6f1c2b9e-0d4a-4c51-9a3e-2b7d8f0e1a22",
      "title": "Kechki jazz",
      "cover_url": "/videos/dQw4w9WgXcQ/thumbnail",
      "item_count": 12,
      "contributors": [
        { "display_name": "Biznesnoma" },
        { "display_name": "IGLEES" },
        { "display_name": "NAVJAAX" }
      ],
      "contributor_count": 7,
      "source": "playlist"
    }
  ]
}

Как вставлять в сетку. Загрузите полку один раз вместе с первой страницей GET /videos и ставьте миксы на фиксированные места: первый, по дизайну, вторым элементом первого ряда (на узком экране первой карточкой), следующие через равный шаг рядов, пока они не кончатся. Полка не зависит от cursor, sort и tag ленты, поэтому при подгрузке следующих страниц её не перезапрашивайте, а в отфильтрованной по тегу или роду ленте не показывайте. Видео, которые есть и в миксе, и в ленте, не убирайте: микс это ссылка на плейлист, а не его содержимое.

Просмотры

POST /videos/{id}/view возвращает {"view_count": 123}.

Зовите его один раз на начало просмотра, а не по таймеру. Для авторизованного зрителя повторный заход в пределах получаса не засчитывается — дедупликация идёт по истории просмотров. Анонимов дедуплицировать нечем, их просмотры считаются всегда. Ответ приходит и в том случае, когда просмотр не зачли: в нём текущее значение счётчика, которое и надо нарисовать.

Каждый засчитанный просмотр, кроме счётчика, попадает в журнал просмотров, по которому считается аналитика владельца (см. «Аналитика»). Правила у них общие: что не увеличило view_count, не попало и в журнал.

Репосты

POST /videos/{id}/share записывает репост и отвечает 204 без тела. Зовите его, когда зритель выбрал способ в поповере «Поделиться» (а не когда поповер открылся). Токен необязателен: поделиться может и аноним.

{ "target": "telegram" }

Тело необязательно: запрос без Content-Type или с {} записывает репост без способа. target — слово до 30 символов из строчной латиницы, цифр, _, - и .: telegram, copy_link, whatsapp и так далее. Список способов на сервере не зашит, но регистр и пробелы не нормализуются, поэтому Telegram или copy link дают 400: иначе один способ расходился бы на несколько написаний. Пустая строка равна отсутствию поля.

Видимость та же, что у просмотра: чужое приватное видео — 404. Повторы не схлопываются (отличить второе нажатие от второго адресата нечем), от накрутки защищает только общий лимит частоты. Счётчика репостов у видео нет: число видит только владелец, в totals.shares аналитики.

Загрузка: три шага

// 1. Создаём запись. visibility по умолчанию private.
const created = await post("/videos", {
  title: "Прогулка по городу",
  description: null,
  location: "Toshkent", // необязательно, см. «Место съёмки»
  category: "music", // необязательно, см. «Категория»
  visibility: "public",
  source_filename: file.name, // необязательно
});
// { video: Video, upload_url: "https://s3...", expires_in: 900 }

// 2. Кладём файл прямо в хранилище. Этот запрос идёт мимо API.
await fetch(created.upload_url, { method: "PUT", body: file });

// 3. Подтверждаем: API сам проверит, что объект появился в хранилище.
await post(`/videos/${created.video.id}/complete`);
// Video со статусом processing

Замечания:

Имя файла и причина отказа

source_filename в POST /videos необязателен. API отрезает путь (по / и \), убирает управляющие символы и пробелы по краям; длиннее 255 символов — 400. Пустое после этого имя хранится как null. Видит его только владелец.

failure_reason появляется у видео в failed и стирается, как только видео снова уходит в перегон:

КодЧто значитПовторять?
unsupported_formatфайл не распознан как видеонет
corruptфайл распознан, но не читается до концанет
no_video_streamв файле нет видеодорожки (например, один звук)нет
internalсбой на стороне серверада

С первыми тремя воркер не тратит попыток и отказывает сразу: тот же файл не перегонится и с третьего раза. Текст ошибки перегона наружу не отдаётся, только код.

Новая ссылка на тот же файл

POST /videos/{id}/upload-url
-> 200 {"upload_url": "https://s3...", "expires_in": 900}

Только владельцу и только пока видео в uploading; иначе 409. Ссылка та же по смыслу, что из POST /videos: PUT целиком, потом /complete. Старая ссылка при этом не отзывается и живёт свой срок. Тела у запроса нет.

Загрузка частями (multipart)

Для больших файлов. Файл режется на части по part_size байт (16 МиБ), каждая часть кладётся своим PUT по своей ссылке, и легшие части хранилище помнит. Обрыв стоит одной части, а не всего файла; после перезагрузки страницы догружается только недостающее, и id видео не меняется.

// 1. Создаём запись, как обычно (POST /videos). Её upload_url не нужен.
const { video } = await post("/videos", { title, visibility });

// 2. Начинаем загрузку частями. size — размер файла в байтах.
const mp = await post(`/videos/${video.id}/multipart`, { size: file.size });
// { upload_id: "…", part_size: 16777216, part_count: 895,
//   parts: [{ n: 1, url: "https://s3..." }, …], expires_in: 900 }

// 3. Кладём части. Часть n — байты [(n-1)*part_size, n*part_size).
//    ETag каждой части берём из заголовка ответа на её PUT.
const res = await fetch(url, { method: "PUT", body: file.slice(from, to) });
const etag = res.headers.get("ETag");

// 4. Ссылки на следующие части (или взамен просроченных) — по номерам,
//    не больше 100 за запрос.
const more = await post(`/videos/${video.id}/multipart/parts`, {
  upload_id: mp.upload_id, numbers: [33, 34, 35],
});
// { parts: [{ n: 33, url: "…" }, …], expires_in: 900 }

// 5. Собираем файл. Части — по возрастанию номера, все до одной.
await post(`/videos/${video.id}/multipart/complete`, {
  upload_id: mp.upload_id,
  parts: [{ n: 1, etag: "\"…\"" }, …],
});
// Video со статусом processing — то же, что ответ /complete

Продолжить после обрыва или перезагрузки:

GET /videos/{id}/multipart                 (или ?upload_id=…)
-> 200 {"upload_id": "…", "part_size": 16777216,
        "parts": [{"n": 1, "etag": "\"…\"", "size": 16777216}, …]}

Без upload_id отвечает про текущую загрузку видео, так что клиенту, который потерял id вместе с вкладкой, достаточно id видео и того же файла. Части из ответа уже лежат; недостающие номера подписываются через /multipart/parts. Сверять, что выбран тот же файл, должен клиент: API файла не видит.

Отменить: DELETE /videos/{id}/multipart?upload_id=… → 204. Видео остаётся в uploading, можно начать заново любым способом.

Замечания:

Перегон заново

POST /videos/{id}/retranscode (владелец) отправляет уже подтверждённое видео через воркер ещё раз. Файл при этом не меняется: ручка нужна, когда поменялись настройки перегона, а исходник остался прежним.

await post(`/videos/${id}/retranscode`);
// Video со статусом processing

Замечания:

Удаление

DELETE /videos/{id} (владелец) отвечает 204 и удаляет запись вместе со всеми файлами видео в хранилище: исходником, сегментами HLS и превью. Удалять можно в любом статусе, в том числе посреди перегона: то, что воркер успеет дописать после удаления, он уберёт сам, когда закончит. Отменённую загрузку (оборванный PUT) удаляют тем же запросом.

Род видео

kind отвечает на вопрос «что это за видео», а status — «в каком оно состоянии». Это разные вопросы: запись трансляции точно так же проходит uploading → processing → ready, как обычная загрузка.

kindчто это
regularобычная загрузка, умолчание
shortкороткое вертикальное видео для деки /shorts
liveзапись прошедшего эфира

live — это архив, а не идущий эфир. Живого вещания в системе нет: ни ingest, ни пакетизатора, ни скользящего окна HLS, и VideoStatus не растёт ради него новым членом. Вкладка Translatsiya и страница /live рисуют законченные трансляции той же карточкой, что и обычные видео, — так они и нарисованы в макете.

Задаётся при создании (POST /videos, поле kind, по умолчанию regular). PATCH /videos/{id} его не трогает: род есть свойство снятого материала, а не настройка, которую переигрывают.

Шортс по исходнику. Род после создания меняет только воркер. Разобрав исходник через ffprobe, он делает regular шортсом, если кадр на экране выше, чем шире, и ролик не длиннее 180 секунд (то же правило height > width && duration <= 180, что проверяет браузер перед POST /videos). Поворот из метаданных учитывается: телефонный ролик, записанный кадром 1920x1080 с поворотом на 90°, вертикальный. Род меняется в той же записи, что переводит видео в ready, поэтому в лентах оно сразу появляется с итоговым родом. Так шортсом становится и файл, который браузер не смог разобрать (HEVC в части сборок Chrome, ProRes, часть MKV) и прислал как regular, и старый вертикальный ролик после POST /videos/{id}/retranscode.

Правило работает только в одну сторону:

Пока видео в uploading или processing, kind равен присланному; верным он становится, когда видео ready. Тег shorts воркер не ставит.

Фильтр ?kind= есть у /videos, у /channels/{id}/videos, у /videos/my и у /videos/my/counts и сочетается с остальными параметрами при любой сортировке. Неизвестное значение отвечает 400. Тот же фильтр с теми же значениями есть у поиска, см. «Поиск». Отсутствие параметра означает «любые», а не «только обычные»: лента без фильтра показывает всё, иначе шортсы пропали бы с главной.

GET /videos?kind=short                  дека /shorts
GET /channels/{id}/videos?kind=live     вкладка Translatsiya
GET /channels/{id}/videos               вкладка Videolar: пока все роды
GET /videos/my?kind=short               студия: только свои шортсы

Последняя строка — известное упрощение: вкладка Videolar показывает и шортсы тоже. Чтобы она показывала только regular, ей нужен ?kind=regular, и это решение клиента, а не сервера.

До этого поля короткие видео опознавались по тегу shorts — строке, которую автор может написать с опечаткой, удалить или занять под обычную тему. Тег остаётся обычным тегом и ничего больше не значит.

Теги

tags задаются при создании и заменяются целиком при правке (PATCH с полем tags). До 15 штук, каждый 1–30 символов. API обрезает пробелы, приводит к нижнему регистру и убирает повторы, так что ["Rust", "rust", " Axum "] превращается в ["rust", "axum"]. Теги участвуют в поиске с меньшим весом, чем заголовок и описание, и по ним же фильтруется лента.

Место съёмки

location задаёт необязательное место съёмки свободным текстом («Toshkent», «Samarqand, Registon»). Его рисует карточка описания на странице просмотра: значок метки и название. Задаётся в POST /videos и меняется в PATCH /videos/{id}, а приходит в каждом Video, где бы видео ни отдавалось: в ленте, поиске, истории, плейлисте, ответе на правку.

API обрезает пробелы по краям. После обрезки допускается до 100 символов (символов, а не байт), на более длинное ответ 400. Пустая строка, в том числе из одних пробелов, ошибкой не считается: в POST это то же, что поля нет, а в PATCH то же, что null, то есть очистка. Поэтому в ответе место либо непустая строка, либо null, и рисовать метку нужно только в первом случае.

Категория

category задаёт одну категорию видео из закрытого словаря, которую выбирает автор. У видео её либо нет (null), либо она одна. Задаётся в POST /videos, меняется в PATCH /videos/{id} и приходит в каждом Video.

Словарь отдаёт GET /categories (без токена) в порядке показа чипов:

[{ "id": "music" }, { "id": "podcasts" }, { "id": "news" }, ...]
idчип в макете
musicMusiqa
podcastsPodkastlar
newsYangiliklar
natureTabiat
animationAnimatsiyalar
gamingв макете нет
educationв макете нет
sportsв макете нет
entertainmentв макете нет

Ответ кэшируется (Cache-Control: public, max-age=3600): словарь меняется только с новой сборкой API. Первые пять id совпадают с id чипов веба, так что чипу достаточно слать ?category= вместо ?tag=.

Названий в ответе нет, и это решение, а не пропуск. Название категории является текстом интерфейса на четырёх языках, и живёт оно в каталогах клиента, как и любые другие подписи. Одна непереведённая строка от API вернула бы ровно ту ошибку, что чинили в #174. Новый слаг, пришедший из /categories раньше, чем клиент получил его перевод, клиенту лучше не рисовать вовсе.

Что категорией не является. Четыре чипа из ряда в макете не категории и в словарь не входят:

чипчто это на самом деле
Barchasiотсутствие фильтра: запрос без category
Pleylistlarдругой ресурс: GET /playlists
Jonli efirlarрод видео: ?kind=live, см. «Род видео»
Yaqinda yuklanganсортировка: ?sort=newest, окно считает клиент

Правила. Слаг сравнивается точно: Music, music и musiqa считаются неизвестными слагами, и на них, как и на пустую строку в теле, API отвечает 400. В PATCH отсутствие поля оставляет категорию как есть, а null убирает её. Фильтр ?category= есть у GET /videos (при любой sort), GET /channels/{id}/videos, GET /videos/search, GET /videos/my и GET /videos/my/counts; он сочетается с kind, tag, q и остальными фильтрами через «И». В query-строке пробелы по краям срезаются, а пустое значение значит «без фильтра»; на неизвестное ответ 400.

Видео, загруженные до категорий. Автоматической разметки нет, с одним исключением: видео, у которого был тег, в точности равный слагу (например music), получило эту категорию при переходе на неё, чтобы /music находил то же, что находил через ?tag=music. Если таких тегов было несколько, взят первый в порядке, в каком их записал автор. Сами теги не тронуты. У остальных старых видео категория null, пока автор её не выберет.

Правка

PATCH /videos/{id} принимает любое подмножество полей title, description, location, category, visibility, tags, thumbnail_id. Отсутствие поля и null различаются:

{ "title": "Новый заголовок" }   // описание, место и категория не тронуты
{ "description": null }          // описание очищено
{ "location": "Toshkent" }       // место задано
{ "location": null }             // место очищено
{ "category": "news" }           // категория задана
{ "category": null }             // категории больше нет
{ "thumbnail_id": "t50" }        // показывать кадр на 50% (см. «Выбор превью»)

Мои видео: вкладки, фильтры, сортировка

GET /videos/my?state=published&visibility=public,unlisted&q=bozor&sort=view_count&order=desc&limit=50
GET /videos/my/counts?q=bozor

Всё, что рисует страница «Videolar» студии, считается на сервере: вкладки со счётчиками, поиск, фильтр «Holati» и сортировка колонок.

ПараметрЗначенияПо умолчанию
statepublished, draft, archivedвсе видео
statusчерез запятую: uploading, processing, ready, failedлюбой
visibilityчерез запятую: public, unlisted, privateлюбая
qслова для поиска в названии и описаниибез поиска
kindодин род: regular, short, live (см. «Род видео»)любой
categoryодна категория из GET /categories (см. «Категория»)любая
sortcreated_at, published_at, view_count, comment_count, like_count, titlecreated_at
orderasc, descdesc

Любое неизвестное значение (в том числе внутри списка) — 400. Без параметров ответ тот же, что и раньше: все свои видео, новые сверху.

Вкладки выводятся из полей, которые уже есть у видео, и это контракт:

stateВкладкаПравило
publishedNashr etilganpublished_at не null и visibility не private
draftQoralamalarpublished_at равен null
archivedArxivdagilarpublished_at не null и visibility = private

Правила точны, потому что published_at ставится один раз (при первой публикации готового видео) и больше не сбрасывается: опубликованное однажды видео черновиком уже не станет. Отдельного состояния «в архиве» нет. Заархивировать — PATCH /videos/{id} с {"visibility": "private"}. Восстановить — PATCH с public или unlisted, и выбирает владелец: прежняя видимость не хранится, и угадывать public значило бы открыть всем видео, которое было доступно только по ссылке.

Поиск q режется на слова по пробелам (первые восемь); видео подходит, если каждое слово нашлось подстрокой без учёта регистра в названии или описании. % и _ ищутся буквально. Пустой q — без поиска.

Сортировка. title — без учёта регистра. При sort=published_at черновики (без даты) идут последними в обе стороны. При равных значениях порядок решает время создания в том же направлении. Курсор помнит sort и order; меняете любой из них или фильтры — начинайте список заново.

GET /videos/my/counts отвечает {"published": 12, "draft": 3, "archived": 1} одним запросом. Принимает те же q, status, visibility, kind и category, что и список (state, sort и order ему не нужны), поэтому при поиске показывает число совпадений на каждой вкладке. Первая страница плюс счётчики — два запроса, сколько бы видео ни было на канале.

Воспроизведение

GET /videos/{id}/playback возвращает один из двух вариантов:

{ "hls_url": "/videos/<id>/hls/master.m3u8" }
{ "source_url": "https://s3...", "expires_in": 3600 }

Первый — готовое видео. Второй отдаётся только владельцу и только пока транскодинг не закончен, чтобы автор мог проверить загрузку сразу. Остальным до готовности приходит 409.

Манифест и сегменты идут через API, а не по presigned-ссылкам: пути внутри манифеста относительные, и подписать их по отдельности плеер не умеет. Поэтому каждый запрос сегмента проверяет видимость видео — и требует токен, если видео не публичное.

Как подключать плеер

// hls.js предпочтительнее нативного HLS везде, где поддерживается.
// Проверять canPlayType первым нельзя: Chromium отвечает "maybe",
// хотя HLS не играет, и вы уйдёте на путь без токена.
if (Hls.isSupported()) {
  const hls = new Hls({
    xhrSetup: (xhr) => xhr.setRequestHeader("Authorization", `Bearer ${token}`),
  });
  hls.loadSource(playback.hls_url);
  hls.attachMedia(video);
} else if (video.canPlayType("application/vnd.apple.mpegurl")) {
  video.src = playback.hls_url; // Safari; приватные видео так не откроются
}

Уровни качества берите из события MANIFEST_PARSED (data.levels), переключение — присваиванием hls.currentLevel (-1 — автовыбор).

Каждая строка #EXT-X-STREAM-INF мастер-плейлиста несёт FRAME-RATE (частота кадров исходника, три знака после точки, например 25.000): перегон fps не меняет, так что у всех ступеней она одна. hls.js кладёт её в level.frameRate, и длина кадра для покадрового шага — это 1 / frameRate. У видео, перегнанных до появления атрибута, его нет, и у файлов, для которых ffprobe не назвал частоту, тоже; тогда берите запасное значение.

Обработчик ERROR обязан считать попытки восстановления: и startLoad(), и recoverMediaError() заново тянут сегменты, а на битом файле ошибка повторяется мгновенно — без счётчика плеер уходит в бесконечный цикл запросов к серверу.

Превью

thumbnail_url — это путь API (/videos/{id}/thumbnail), а не ссылка на хранилище. Берите его целиком, не собирайте сами: у приватного видео он бывает подписан.

Тег <img> не умеет отправлять Authorization, а превью приватного видео отдаётся только владельцу. Поэтому владельцу (в GET /videos/my, в GET /videos/{id} и в ответах на собственные POST/PATCH над видео, в содержимом и обложках плейлистов) thumbnail_url приватного видео приходит подписанным:

/videos/dQw4w9WgXcQ/thumbnail?exp=1790000000&sig=Zk9v...

Такая ссылка открывается без токена, обычным <img src>, с любого origin. sig — HMAC-SHA256 над коротким id видео и exp (unix-время, секунды); ключ выводится из JWT__SECRET, так что его смена отзывает и выданные ссылки. Живёт ссылка 15–20 минут: exp округлён до пяти минут, и пять минут подряд ссылка одна и та же, поэтому браузер не качает картинку заново при каждом обновлении списка. После exp, с подделанным sig или exp, или с подписью другого видео приватное превью без токена — 404, как и без подписи. Истёкшую ссылку обновляет повторный запрос списка или карточки.

Публичным и доступным по ссылке видео подпись не нужна, и их thumbnail_url остаётся голым путём. Ответ на превью всегда Cache-Control: private, max-age=300 и X-Content-Type-Options: nosniff.

Выбор превью

thumbnail_url всегда ведёт на выбранное превью, и это то же поле, что и раньше: показывающим превью клиентам о выборе знать не нужно. После выбора в ссылке появляется ?v=<метка> (?v=t50, ?v=custom-…): сервер её не читает, она лишь меняет адрес, чтобы браузер не показывал пять минут закэшированное старое превью. У auto метки нет.

Варианты (thumbnail_id):

GET /videos/{id}/thumbnails (владелец) перечисляет только существующие варианты, в этом порядке:

[
  { "id": "auto", "url": "/videos/dQw4w9WgXcQ/thumbnails/auto?exp=…&sig=…", "selected": false },
  { "id": "t25", "url": "/videos/dQw4w9WgXcQ/thumbnails/t25?exp=…&sig=…", "selected": false },
  { "id": "t50", "url": "/videos/dQw4w9WgXcQ/thumbnails/t50?exp=…&sig=…", "selected": true },
  { "id": "t75", "url": "/videos/dQw4w9WgXcQ/thumbnails/t75?exp=…&sig=…", "selected": false },
  {
    "id": "custom",
    "url": "/videos/dQw4w9WgXcQ/thumbnails/custom?v=custom-…&exp=…&sig=…",
    "selected": false
  }
]

url каждого варианта подписан так же, как thumbnail_url (см. «Превью»), и открывается в <img> без токена при любой видимости видео: варианты видит только владелец. Без подписи GET /videos/{id}/thumbnails/{t} отдаёт вариант лишь по токену владельца, остальным — 404.

Выбор — PATCH /videos/{id} с {"thumbnail_id": "t50"}, ответ — Video. Несуществующий вариант (кандидат, который воркер не снял, или custom без загруженной картинки) — 409, и остальные поля того же запроса не применяются; неизвестное значение — ошибка разбора тела. Перегон видео сохраняет выбор, кроме случая, когда выбранный кадр-кандидат не удалось снять заново: тогда превью возвращается к auto.

Своя картинка загружается как видео, мимо API:

  1. POST /videos/{id}/thumbnail/upload → {"upload_url": "...", "expires_in": 900, "max_bytes": 2097152};
  2. PUT upload_url с телом картинки (JPEG, PNG или WebP, не больше 2 МБ);
  3. POST /videos/{id}/thumbnail/complete → Video, где thumbnail_url уже ведёт на новую картинку, а thumbnail_id выбран custom.

/complete проверяет сам файл в хранилище, а не то, что о нём сказал клиент: размер — по HEAD, формат — по первым байтам. Файл больше 2 МБ или не JPEG, PNG и WebP — 400, и он удаляется; файла нет — 409. Тип ответа превью определяется по тем же байтам, Content-Type из PUT значения не имеет. Загружать можно в любом статусе видео, в том числе пока оно в обработке. Повторная загрузка заменяет прежнюю картинку.

Субтитры

Субтитры загружает автор видео: файл WebVTT, одна дорожка на язык. Распознавания речи нет, и воркер субтитров не создаёт, поэтому auto всегда false. В мастер-плейлист HLS дорожки не попадают (#EXT-X-MEDIA:TYPE=SUBTITLES нет): клиент подключает их сам, элементом <track>, а не через hls.js.

Какие дорожки есть

GET /videos/{id} (VideoDetail) несёт captions всегда, даже пустым списком: [] — честный ответ «субтитров нет», и меню плеера по нему прячет строку «Субтитры». Дорожки идут в порядке lang.

"captions": [
  {
    "lang": "uz",
    "label": "Oʻzbekcha",
    "url": "/videos/kBeaJSmGT7c/captions/uz.vtt?v=3f2a…",
    "kind": "subtitles",
    "auto": false
  }
]

В лентах, поиске, списках и ответах на POST/PATCH над видео поля captions нет: оно стоило бы ещё одного запроса к базе на каждую страницу ради меню, которое открывают только в плеере. Список дорожек берите из карточки, которую плеер и так запрашивает.

label — то, что автор прислал при загрузке, а если не прислал — самоназвание языка: uz → «Oʻzbekcha», uz-Cyrl → «Ўзбекча», ru → «Русский», en → «English». Для остальных языков подпись по умолчанию — сам тег (de), так что для них автору стоит прислать свою.

Как подключать

url — путь этого API, как thumbnail_url и hls_url, а не ссылка на хранилище. Пропускайте его через тот же резолвер медиа-путей, что и thumbnail_url (MediaUrlResolver / resolveMedia из @tes-tube/core/wire): в браузере он даёт путь того же origin с префиксом /v1, на сервере — абсолютный адрес API. Сами адрес не собирайте: у приватного видео он подписан, а ?v= меняется с каждой загрузкой.

<video>
  <track
    kind="subtitles"
    src="/v1/videos/kBeaJSmGT7c/captions/uz.vtt?v=3f2a…"
    srclang="uz"
    label="Oʻzbekcha"
  />
</video>

GET /videos/{id}/captions/{lang}.vtt отдаёт файл с Content-Type: text/vtt; charset=utf-8, X-Content-Type-Options: nosniff и Cache-Control: private, max-age=300, как сегменты HLS. Файл идёт через API, а не по presigned-ссылке, и каждый запрос проверяет видимость видео так же, как GET /videos/{id}/hls/{path}: приватное видео без токена владельца — 404, а не 403. Нет такой дорожки или путь без .vtt — тоже 404. v сервер не читает: он лишь меняет адрес после новой загрузки, чтобы браузер не держал пять минут прежний файл.

<track>, как и <img>, не умеет приложить Authorization. Поэтому владельцу приватного видео url приходит подписанным, той же подписью, что thumbnail_url (см. «Превью»): …/uz.vtt?v=…&exp=…&sig=… открывается без токена 15–20 минут, потом карточку нужно запросить заново. Публичным и доступным по ссылке видео подпись не нужна. <track> с другого origin браузер грузит только с атрибутом crossorigin на <video>; веб ходит в API тем же origin (/v1/), и там это не нужно.

Загрузка

Как у своего превью: ссылка, файл прямо в хранилище, подтверждение.

// 1. Ссылка для загрузки. Тело необязательно; без label подпись — самоназвание языка.
const { upload_url, expires_in, max_bytes } = await post(`/videos/${id}/captions/uz-Cyrl`, {
  label: "Ўзбекча (кирилл)",
});

// 2. Файл прямо в хранилище, без заголовка Authorization.
await fetch(upload_url, { method: "PUT", body: file });

// 3. Подтверждение: API проверяет файл и отдаёт CaptionTrack.
const track = await post(`/videos/${id}/captions/uz-Cyrl/complete`);

DELETE /videos/{id}/captions/{lang} снимает дорожку и её файл, а заодно начатую на этот язык загрузку; ответ — 204, а если не было ни того, ни другого — 404. Удаление видео удаляет и все его субтитры.

Реакции

МетодПутьТелоОтвет
PUT/videos/{id}/reaction{"reaction": "like"}счётчики
DELETE/videos/{id}/reaction—счётчики
GET/videos/{id}/reaction—счётчики и свой голос
{ "likes": 12, "dislikes": 1, "my_reaction": "like" }

Реакция у пользователя одна: PUT с другим значением переносит голос, а не добавляет второй. Все три ручки требуют токен. Счётчики в карточке видео (like_count, dislike_count) обновляются той же транзакцией, так что после ответа можно просто перерисовать число из него.

Комментарии

МетодПутьДоступ
GET/videos/{id}/commentsпо видимости, курсор
POST/videos/{id}/commentsтокен, тело {"body": "...", "parent_id": null}
GET/comments/{id}/repliesпо видимости, курсор
PATCH/comments/{id}только автор
DELETE/comments/{id}автор или владелец видео
PUT/comments/{id}/likeтокен
DELETE/comments/{id}/likeтокен
PUT/comments/{id}/dislikeтокен, ответ 204
DELETE/comments/{id}/dislikeтокен, ответ 204
GET/me/commentsтокен, только свои видео, курсор

Длина текста — 1–10 000 символов после обрезки пробелов. Владелец видео может удалять чужие комментарии под своим роликом, но не править их. Правка проставляет edited_at — по нему и рисуется метка «изменено»; updated_at для этого не годится, его двигают и служебные пересчёты счётчиков.

Ответы двухуровневые, как в макете: корень, ответ на него и ответ на ответ. GET /videos/{id}/comments отдаёт только верхний уровень с reply_count у каждого. GET /comments/{id}/replies отдаёт прямые ответы на комментарий {id}, старые сверху (ветку читают как разговор), с тем же курсором, что и везде; {id} может быть и корнем, и ответом. Ответы на ответ в выдачу корня не попадают: их разворачивают тем же запросом с id ответа.

reply_count есть у каждого комментария и считает только прямые ответы, ровно столько вернёт /comments/{id}/replies. У ответа он показывает, нужен ли переключатель «N ta javob» под ним; у ответа второго уровня он всегда 0. Число всего обсуждения под плеером — comment_count видео, оно считает все уровни.

parent_id в POST указывает на корень или на ответ первого уровня этого же видео. Ответ на ответ второго уровня — 400 (третьего уровня нет), чужой или несуществующий родитель — 404. Удаление комментария уносит все ответы под ним на любой глубине; reply_count его родителя и comment_count видео пересчитываются той же транзакцией.

?sort=top сортирует верхний уровень по лайкам вместо свежести.

Лайки и дизлайки устроены как реакция на видео: у зрителя на комментарий один голос. PUT .../dislike снимает его лайк, PUT .../like снимает его дизлайк. DELETE снимает только названную реакцию: DELETE .../like не трогает дизлайк, и наоборот. Все четыре ручки идемпотентны: повторное нажатие не удваивает счётчик, снять то, чего нет, тоже успех. Голосовать можно за то, что видно: комментарий под чужим приватным видео даёт 404.

Дизлайк отвечает 204 без тела. Лайк по-прежнему отвечает 200 с телом {"like_count", "dislike_count", "my_reaction", "liked_by_me"}: два последних поля добавлены, потому что лайк теперь двигает оба числа. Перерисовать строку можно и из него, и из следующего чтения ленты.

У каждого Comment (лента, ветка ответов, ответ на POST и PATCH, /me/comments) есть like_count, dislike_count и my_reaction. Оба счётчика публичны и приходят и анониму, потому что макет рисует число на пилюле дизлайка. Продакт может позже решить скрыть число дизлайков, как YouTube; тогда пропадёт dislike_count, а пара ручек останется. О дизлайке автору не сообщают, уведомлений о голосах нет вовсе.

my_reaction показывает собственный голос: "like", "dislike" или null. У анонима он всегда null. liked_by_me оставлен ради совместимости и выводится из my_reaction: true при "like", false при "dislike" и без голоса, null у анонима. Новый код читает my_reaction. Ответы на PATCH собирают комментарий без зрителя, поэтому там оба поля null.

Комментарий под чужим видео создаёт уведомление владельцу, ответ — автору того комментария, на который ответили (корня или ответа). Себе уведомления не приходят.

Комментарии канала

GET /me/comments — одна лента комментариев под всеми видео вызывающего, любой видимости (public, unlisted, private), для страницы комментариев в студии. Комментариев под чужими видео в ней нет, даже своих.

ПараметрЗначение
video_idпубличный id одного своего видео; чужое или несуществующее — []
qподстрока текста, логина или имени автора, без учёта регистра
sortnewest (по умолчанию) или top — по лайкам
scoperoots (по умолчанию) — только верхний уровень; all — и ответы
cursorкак везде; курсор от другой sort — 400
limit1–100, по умолчанию 20

q ищет буквально: % и _ в нём — обычные символы, а не шаблон. Пустой q фильтром не считается. Неизвестное значение sort или scope, как и нечисловой limit, дают 400.

Элемент — обычный Comment и ещё два поля:

interface MyComment extends Comment {
  video: {
    id: string; // публичный id, тот же, что в Comment.video_id
    title: string;
    thumbnail_url: string | null;
    visibility: "public" | "unlisted" | "private";
  };
  replied_by_owner: boolean;
}

replied_by_owner — владелец канала ответил прямо на этот комментарий. У корня засчитывается и ответ владельца на любой ответ в его ветке; у ответа любого уровня — и реплика владельца рядом с ним, у того же родителя, но позже него. my_reaction и liked_by_me здесь показывают голос самого владельца.

Каналы и подписки

МетодПутьДоступОписание
GET/channels/{id}всеКарточка канала
GET/channels/by-username/{username}всеОна же по имени из ссылки
GET/channels/{id}/videosвсеПубличные видео, sort, kind
PATCH/me/channelтокенПравка своего профиля
POST/me/channel/avatarтокенСсылка для загрузки
POST/me/channel/avatar/completeтокенПодтвердить загрузку
POST/me/channel/bannerтокенСсылка для загрузки
POST/me/channel/banner/completeтокенПодтвердить загрузку
GET/channels/{id}/avatarвсеАватар (картинка)
GET/channels/{id}/bannerвсеБаннер (картинка)
GET/link-icons/{hash}всеЗначок сайта из ссылки канала
GET/me/profileтокенСвои личные данные
PATCH/me/profileтокенПравка личных данных
PUT/channels/{id}/subscriptionтокенПодписаться / колокольчик
DELETE/channels/{id}/subscriptionтокенОтписаться
GET/subscriptionsтокенМои подписки, offset
GET/feedтокенЛента подписок, курсор

Идентификатор канала — это channel.id из карточки видео. Адресовать канал можно и по имени: /channels/by-username/neo или /channels/by-username/@neo — ведущая @ принимается, регистр не важен.

Подписка и отписка идемпотентны: повтор возвращает тот же 204. Подписка на себя — 400, на несуществующий канал — 404. Тело PUT необязательно; {"notifications_enabled": false} оставляет подписку, но выключает уведомления о новых видео. Тем же запросом колокольчик и переключают.

Строки GET /subscriptions — те же карточки Channel, что у GET /channels/{id}: subscribed в них всегда true, а notifications_enabled — настоящее состояние колокольчика. Перечитывать каждый канал ради него не нужно.

{
  "items": [{ "id": "...", "username": "neo", "subscribed": true, "notifications_enabled": false }],
  "limit": 20,
  "offset": 0
}

Видео канала: сортировка

GET /channels/{id}/videos?sort=most_viewed&limit=20

Это лента GET /videos, суженная до одного канала, с теми же значениями sort и той же семантикой: newest (по умолчанию), oldest, most_viewed, trending. Чипы вкладки «Видео» — «Eng yangi», «Mashxur», «Eng eski» — это newest, most_viewed и oldest. Неизвестное значение — 400. Курсор привязан к сортировке, под которой выдан: смена sort без сброса cursor даёт 400 (см. «Пагинация»). Отдельного фильтра channel_id у /videos нет: ссылка «видео канала» живёт здесь. kind и category работают так же, как у /videos.

Правка профиля

PATCH /me/channel
{
  "display_name": "Нео",
  "description": "про матрицу",
  "about": "длинный текст вкладки «о канале»",
  "avatar_url": "https://...",
  "banner_url": null,
  "country": "UZ",
  "links": [{"label": "Сайт", "display": "example.com", "url": "https://example.com"}]
}

Все поля необязательны. Отсутствие поля означает «не трогать», явный null — «очистить»; строка из одних пробелов равносильна null. links заменяется целиком (до 10 штук). Адрес ссылки принимается только со схемой http://, https:// или mailto: — он уходит в href на клиенте, и javascript: там был бы XSS. icon_url в ссылках запроса пропускается молча: значок выводит сервер из адреса (см. «Значки ссылок»). Отказ 400 сломал бы клиента, который отправляет назад ссылки ровно в том виде, в каком их прочитал, вместе с icon_url.

Значения нормализуются при записи и читаются уже нормализованными: country приводится к верхнему регистру ("uz" → "UZ"), а label, display и url каждой ссылки обрезаются по краям (" Sayt " → "Sayt").

avatar_url и banner_url, записанные руками, принимаются только как https://... без пробелов, не длиннее 2000 символов и только на хосте из списка разрешённых (настройка сервера APP__MEDIA__AVATAR_HOSTS, точное совпадение имени). Иначе — 400: data:, javascript:, http: и любой другой хост. По умолчанию список пуст, то есть внешний адрес не принимается никакой, и картинку нужно загрузить. Причина: картинку со стороннего хоста каждый зритель запрашивает сам, и владелец хоста видит адрес, браузер и время каждого, кому показали комментарий или уведомление с этим аватаром. Правило проверяет только новые адреса. Записанные до него ссылки https:// сохранены на любом хосте и приходят как есть; прочие (javascript:, data:, http:) обнулены миграцией и приходят как null. Сохранённая ссылка, присланная назад без изменений вместе с остальной формой, означает «не трогать» и 400 не вызывает. Путь этого API (/channels/...) руками не записать: его ставит только загрузка (см. ниже), и любой путь, кроме текущего, — 400. Текущее значение, отправленное назад вместе с остальной формой, означает «не трогать». Любая другая запись (новый адрес или null) отвязывает загруженную картинку, и её файл удаляется.

username не меняется вовсе: он адресует канал, и смена сломала бы все ссылки @username. Тело с ключом username (с любым значением, в том числе null) отвергается целиком: 400 {"error": "...username нельзя изменить..."}, и остальные поля этого запроса тоже не применяются. Остальные незнакомые ключи по-прежнему молча пропускаются: отвергать их все значило бы ломать клиентов, которые шлют форму с лишними безвредными полями, а тихий 200 опасен только для username, который клиент мог бы счесть сохранённым.

Ответ — та же карточка канала, что и у GET /channels/{id}.

Личные данные

GET /me/profile        (токен)
-> 200 {"first_name": "Aziz", "last_name": null, "phone": "+998901234567", "email": "aziz@example.com"}

PATCH /me/profile      (токен)
{"first_name": "Aziz", "last_name": "Karimov", "phone": "+998901234567"}
-> 200 тот же объект

Имя, фамилия и телефон — данные человека, а не канала: их отдаёт только /me/profile и только владельцу токена. Ни карточка канала, ни /auth/me, ни комментарии, ни любая другая ручка их не содержат.

Смена email

POST /me/email               (токен)
{"email": "new@example.com"}
-> 202 (тело пустое)
-> 409 {"error": "..."}   адрес уже занят другим аккаунтом

POST /me/email/confirm       (токен)
{"code": "04217"}
-> 200 User               (новый email, "email_verified": true)
-> 400 {"error": "..."}   неверный, просроченный или сожжённый код
-> 409 {"error": "..."}   адрес успели занять, пока шёл код

Аватар и баннер

Загрузка устроена как у видео: ссылка, файл прямо в хранилище, подтверждение.

// 1. Ссылка для загрузки. Для баннера — /me/channel/banner.
const { upload_url, expires_in } = await post("/me/channel/avatar");

// 2. Файл прямо в хранилище, без заголовка Authorization.
await fetch(upload_url, { method: "PUT", body: file });

// 3. Подтверждение: API проверяет файл и отдаёт карточку канала.
const channel = await post("/me/channel/avatar/complete");
// channel.avatar_url === "/channels/<id>/avatar?v=<версия>"

Значки ссылок

У каждой ссылки канала есть icon_url: значок сайта, на который она ведёт. Он приходит везде, где приходят ссылки: GET /channels/{id}, GET /channels/by-username/{username}, GET /subscriptions, ответы PATCH /me/channel и /me/channel/{avatar,banner}/complete.

"links": [
  { "label": "Instagram", "display": "@eslcs", "url": "https://instagram.com/eslcs",
    "icon_url": "/link-icons/5b1f0c6c…e2" },
  { "label": "Gmail", "display": "eslcs@gmail.com", "url": "mailto:eslcs@gmail.com",
    "icon_url": null }
]

Как сервер ищет значок: https://{host}/favicon.ico, а если его нет, то первый <link rel="icon">, rel="shortcut icon" или rel="apple-touch-icon" с главной страницы https://{host}/. Ходит он только по https, только на порт 443, только на сам хост или его поддомен, не дальше трёх перенаправлений и не дольше 5 секунд на хост; адрес, который резолвится во внутреннюю сеть (loopback, частные сети, link-local, CGNAT и прочее не глобальное), отвергается до соединения. Файл больше 256 КБ не принимается. Принимаются PNG, ICO, JPEG, GIF и WebP, формат определяется по первым байтам; SVG не принимается никогда: внутри него бывает скрипт.

GET /link-icons/{hash} отдаёт файл без токена, с типом, определённым по сигнатуре, X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none' и Cache-Control: public, max-age=31536000, immutable: значок хоста скачивается один раз и больше не меняется. Хэш, которого нет, или значок, который ещё не скачан, дают 404.

Поиск

GET /videos/search?q=прогулка+по+городу&limit=20&offset=0

Ищет по заголовку и описанию публичных готовых видео; заголовок весит больше. Запрос разбирается как в поисковике: кавычки задают точную фразу, -слово исключает. Пустой q — 400. Результаты отсортированы по релевантности, затем по свежести.

Фильтры поиска

GET /videos/search?q=bozor&category=music&kind=short&watched=false&limit=20&offset=0

Все четыре параметра необязательны, складываются через «И» и сочетаются с q, limit и offset. Они только сужают выдачу: порядок остаётся тем же, по релевантности.

параметрзначениячто делает
categoryслаг из GET /categoriesкак GET /videos?category=: чипы категорий
tagодин тегкак GET /videos?tag=: свободный тег автора
kindregular, short, liveкак GET /videos?kind=, см. «Род видео»
watchedtrue, falseесть ли видео в истории зрителя; нужен токен

Какой ряд чипов на /results канонический (категории на 1920 или род и история на 430), решает продукт; API отдаёт оба.

Подсказки (/videos/search/suggest) этих фильтров не принимают: они дополняют строку ввода, а чипы относятся к уже найденной выдаче.

Подсказки

GET /videos/search/suggest?q=биз&limit=8

{ "suggestions": ["Ermak Biznes segodnya", "Biznes s nulya"] }

Отдаёт строки, а не видео: подсказка заполняет строку ввода, и вычитывать заголовки из полного ответа /videos/search, чтобы получить восемь строк, — это обход, а не решение. Не вызывайте ради подсказок /videos/search.

Чего ручка не делает: она не знает, что люди ищут, и не предложит слово, которого никто не опубликовал. Для этого нужен журнал запросов, а он упирается в решения о сроке хранения и о том, записывать ли запросы анонимов.

История просмотров

МетодПутьДоступОписание
PUT/videos/{id}/progressтокенСохранить позицию
GET/videos/{id}/progressтокенГде остановились
GET/me/historyтокенИстория, q
DELETE/me/history/{id}токенУбрать одно видео
DELETE/me/historyтокенОчистить целиком
PUT /videos/dQw4w9WgXcQ/progress
{"position_secs": 42.5, "watched_delta_secs": 10, "completed": false}

watched_delta_secs — приращение с прошлого отчёта, а не «сколько всего»: суммарного времени клиент не знает, смотреть могли и с другого устройства. Отправляйте отчёт раз в 10 секунд воспроизведения, а не на каждый тик. Один отчёт засчитывает не больше 21 600 секунд (6 часов): больше API не отвергает, а урезает, и отвечает 200. Так отчёт, накопивший секунды после обрыва сети, не застревает на 400. Отрицательное приращение по-прежнему 400. Сумма watched_secs одной строки истории не растёт выше 1e9 секунд.

completed только взводится: досмотрев ролик и перемотав назад, зритель не делает его недосмотренным. Порог «досмотрено» решает клиент — он знает и длительность, и то, что для тридцатисекундного ролика и двухчасового фильма это разный запас.

GET /videos/{id}/progress отвечает 404, если это видео ещё не смотрели: «нечего возобновлять» — отсутствие записи, а не нулевой прогресс, который пришлось бы отличать от настоящего нуля.

Строка /me/history — это карточка видео плюс поле progress:

{
  "id": "dQw4w9WgXcQ",
  "title": "...",
  "channel": {},
  "progress": {
    "position_secs": 42.5,
    "watched_secs": 60,
    "completed": false,
    "last_watched_at": "2026-09-07T10:00:00Z"
  }
}

Удалённые и ставшие приватными чужие видео из истории выпадают сами.

Поиск по истории

GET /me/history?q=bozor&limit=20

q ищет по всей истории, а не по загруженным страницам: фильтр на клиенте говорил бы «ничего нет», пока совпадение лежит на следующей странице. Строка режется на слова по пробелам (берутся первые восемь), и запись подходит, если каждое слово нашлось подстрокой без учёта регистра в названии видео или в имени канала (channel.display_name). Это не полнотекстовый поиск /videos/search: тот стеммит по-русски и не находит узбекское слово по его части. % и _ ищутся буквально. Пустой или пробельный q — вся история, как без параметра. Порядок (недавние сверху), конверт и правила курсора те же; меняете q — начинайте список заново.

Смотреть позже и понравившееся

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

МетодПутьДоступОписание
GET/me/watch-laterтокенСписок, курсор
GET/me/watch-later/{id}токенЕсть ли: 204 / 404
PUT/me/watch-later/{id}токенПоложить наверх, идемпотентно
PUT/me/watch-later/{id}/positionтокенПереставить
DELETE/me/watch-later/{id}токенУбрать одно видео
DELETE/me/watch-laterтокенОчистить целиком
GET/me/likedтокенЧто лайкнул, курсор

Это не плейлисты. У них нет названия, описания и видимости, их нельзя переименовать или удалить, и в GET /playlists они не появляются. Не изобретайте вместо них приватный плейлист с зарезервированным названием: зритель увидит его в своём списке и в панели «сохранить в плейлист» и сможет удалить из-под функции, а название придётся либо показывать как внутренний токен, либо переводить на четыре локали.

Замечания:

Перестановка в «Смотреть позже»

PUT /me/watch-later/{id}/position
{"position": 0}                     -> 200 {"position": 0}

Плейлисты

МетодПутьДоступОписание
POST/playlistsтокенСоздать
GET/playlists?owner_id=по видимостиБиблиотека, offset
GET/playlists/{id}по видимостиКарточка
PATCH/playlists/{id}владелецПравка
DELETE/playlists/{id}владелецУдалить
GET/playlists/{id}/itemsпо видимостиСодержимое по порядку, offset
POST/playlists/{id}/itemsвладелецДобавить видео в конец
PUT/playlists/{id}/items/{video_id}владелецПереставить
DELETE/playlists/{id}/items/{video_id}владелецУбрать
GET/videos/{id}/playlistsтокенВ каких моих плейлистах уже есть
GET/me/saved-playlistsтокенСохранённые чужие, offset
PUT/me/saved-playlists/{id}токенСохранить чужой, идемпотентно
DELETE/me/saved-playlists/{id}токенУбрать из библиотеки

GET /playlists без owner_id показывает свою библиотеку целиком; с чужим owner_id — только публичные плейлисты этого канала. Без токена и без owner_id — 401: чья библиотека, неизвестно.

Повторное добавление того же видео — 409, а не второй экземпляр. Чужое приватное видео в плейлист не кладётся (404): это был бы обход приватности. Наоборот тоже: приватные видео не отдаются из чужого публичного плейлиста.

Позиции плотные и считаются с нуля. PUT .../items/{video_id} с {"position": 0} двигает видео в начало, сдвигая остальных; позиция за пределами списка прижимается к краю, и ответ говорит, куда видео встало на самом деле. Удаление подтягивает позиции за собой, дыр не остаётся.

cover_video_id — короткий id первого видео плейлиста, а cover_thumbnail_url — готовая ссылка на его превью (null, если видео нет или превью у него ещё нет). Рисуйте обложку из cover_thumbnail_url, а не собирайте путь из cover_video_id: если обложка — ваше же приватное видео, ссылка подписана (см. «Превью») и открывается в <img> без токена.

GET /videos/{id}/playlists возвращает массив UUID — это галочки в меню «сохранить в плейлист».

Сохранённые плейлисты

Чужой плейлист можно сохранить в свою библиотеку, не копируя его: правки автора видны сразу. GET /me/saved-playlists?limit=&offset= отдаёт те же карточки Playlist, что и GET /playlists, в том же offset-конверте, недавно сохранённые сверху. Чтобы собрать библиотеку целиком, склейте его с GET /playlists: свои плейлисты в сохранённых не появляются.

Автор уже есть в карточке, плоскими полями owner_id, owner_username, owner_display_name и owner_avatar_url, по тому же соглашению, что и у автора комментария. Подпись «<канал> · Pleylist» собирайте из них; вложенного объекта owner нет, чтобы одно и то же не приходило дважды.

GET /playlists/{id} дополнительно отдаёт saved_by_me: boolean | null: null без токена, false на своём плейлисте. В списках этого поля нет.

Замечания:

Уведомления

МетодПутьОписание
GET/notifications?unread=trueЯщик, курсор
GET/notifications/unread-countЦифра на колокольчике
POST/notifications/{id}/readОтметить прочитанным
POST/notifications/readОтметить прочитанным весь ящик
DELETE/notifications/{id}Убрать из ящика

Все требуют токен. Уведомления создаются сами:

Если видео, о котором уведомление, удалено или стало приватным (и оно не ваше), уведомление остаётся в ящике, но video_id и video_title приходят null. Рисуйте такую строку без ссылки на видео.

Чужое уведомление отвечает 404 и на отметку, и на удаление.

Жалобы

МетодПутьДоступ
POST/videos/{id}/reportтокен
GET/me/reportsтокен, offset
POST /videos/dQw4w9WgXcQ/report
{"reason": "spam", "details": "сплошная реклама"}

reason — из перечисления ReportReason; неизвестное значение даёт 422. Для other пояснение обязательно (400 без него), в остальных случаях — необязательно, до 1000 символов. Повторная жалоба того же человека на то же видео — 409: форму отправляют дважды случайно, и это не должно выглядеть как две жалобы.

Разбор жалоб живёт вне API: status меняет модератор, клиент видит его в /me/reports.

Аналитика

МетодПутьДоступОписание
GET/me/analyticsтокенДашборд Студии: весь канал
GET/videos/{id}/analyticsвладелецТо же для одного видео

Период задаётся либо period, либо парой from и to:

GET /me/analytics?period=7d          (7d, 30d, 90d, all; без параметров — 30d)
GET /me/analytics?from=2026-09-01&to=2026-09-23

Дни считаются по UTC, обе границы включительно; 7d — сегодня и шесть дней перед ним. all начинается в день регистрации канала (у видео — в день его создания). Свой диапазон — не длиннее 3660 дней; period вместе с from/to, одна граница без другой или from позже to — 400.

{
  "period": {
    "from": "2026-09-17",
    "to": "2026-09-23",
    "days": 7,
    "previous_from": "2026-09-10",
    "previous_to": "2026-09-16"
  },
  "totals": {
    "views": 120,
    "watch_time_secs": 5400,
    "subscribers_gained": 4,
    "subscribers_lost": 1,
    "likes": 10,
    "comments": 3,
    "shares": 2
  },
  "previous": { "...": "те же ключи за previous_from..previous_to" },
  "daily": [
    {
      "date": "2026-09-17",
      "views": 20,
      "watch_time_secs": 800,
      "subscribers_gained": 1,
      "subscribers_net": 0
    }
  ],
  "audience": { "views_by_subscribers": 70, "views_by_non_subscribers": 50 },
  "basis": {
    "signed_in_only": ["watch_time_secs", "daily.watch_time_secs"],
    "unknown": [],
    "events_since": "2026-10-06T09:12:44.123456Z"
  }
}

previous — период той же длины вплотную перед текущим, для дельт на карточках. У all сравнивать не с чем: previous, previous_from и previous_to — null. daily идёт без пропусков, день без событий приходит нулями.

Числа собраны из двух источников, и ответ говорит сам в basis, какое число чем является. Рисовать стоит по нему, а не по этому тексту.

Журналы событий (вторая фаза): просмотры, репосты, подписки и отписки.

Журналы начинаются с момента обновления, basis.events_since. Раньше него просмотров по дням, репостов и отписок не записано нигде, и за более ранние дни эти поля приходят нулями: это «неизвестно», а не «никого не было». Числа фазы 1 за те дни (просмотры из истории вошедших зрителей) не подмешиваются: у них другой смысл, и один график из двух источников выглядел бы как обрыв аудитории в день обновления. Если from раньше events_since, отметьте эту часть оси. Подписки, действовавшие в момент обновления, перенесены в журнал с их настоящим временем, поэтому прирост за прошлые дни виден (кроме тех, кто успел отписаться до обновления).

Существующие таблицы, как в первой фазе:

Остальное:

Служебное

МетодПутьОписание
GET/healthЖив ли процесс
GET/health/readyДоступны ли БД и хранилище (503, если нет)
GET/metricsЭкспозиция Prometheus
GET/docsЭтот документ страницей для браузера
GET/docs.mdОн же исходником в Markdown, для инструментов

Типовой сценарий

  1. POST /auth/register, /auth/login или /auth/google → сохранить обе половины пары; по истечении expires_in — POST /auth/refresh.
  2. GET /videos?sort=trending&limit=20 → лента; листать по next_cursor. Карточка канала уже внутри каждого элемента.
  3. GET /videos/{id} + GET /videos/{id}/playback → карточка и плеер, POST /videos/{id}/view один раз на старте, GET /videos/{id}/progress → предложить продолжить с сохранённой позиции.
  4. GET /videos/{id}/comments, GET /videos/{id}/reaction, GET /videos/{id}/related → обсуждение и колонка «дальше».
  5. Во время воспроизведения — PUT /videos/{id}/progress раз в 10 секунд.
  6. Загрузка: POST /videos → PUT upload_url → POST /complete (большой файл — частями через /multipart, см. «Загрузка частями»), дальше опрашивать GET /videos/{id}, пока status не станет ready (транскодинг идёт в фоне, уведомлений о его ходе нет).

Чего в API нет

Об этом стоит знать заранее, чтобы не искать: