Изменения API

Что есть в API ВИШ сейчас, что менялось и как мы предупреждаем о несовместимых изменениях. Страница обновляется вместе с API; последняя сверка — 23 октября 2026 года, d1 и production.

Версия v1 сегодня

Все методы — под /api/v1; описание каждого — в OpenAPI стенда (/documentation, машинный вид — /documentation/json).

История

В разработке (d1), октябрь 2026

• «Вход через ВИШ» — OAuth 2.1 и OpenID Connect: документ настройки, /oauth/token, /oauth/userinfo, /oauth/revoke, /oauth/introspect, ключи подписи ES256. Регистрация своих приложений — на странице «Для разработчиков» для владельцев действующего ключа.
• Модель данных университета (/university/…) — для сотрудников с правами.
• Выгрузки расписания (/exports/…) в CSV для всех и в JSON — по праву analytics:export.
• Новые права и роли. analytics:export — выгрузка аналитики файлом (его получили все роли, у которых уже было analytics:read); places:read, places:write, leads:read, leads:write, ads:read, ads:draft, ads:manage — для разделов мест, партнёров и рекламы, которые ещё готовятся; роли analyst, sales и adsManager. Открытия аналитики (analytics:read) теперь пишутся в журнал аудита — не чаще одной записи на человека и эндпоинт за 10 минут.
• Раздел «Разработчикам» в справочнике — эти страницы с примерами, которые проверяются на d1.

0.12 — 20 октября 2026

• Выпуск ключа себе без заявки (POST /api-keys/mine) — для ролей с правом api:keys:self-issue; срок до 730 дней.
• Месячный отчёт института как данные: GET /reports/institute?month=ГГГГ-ММ — только сводные числа.

0.11 — 7 октября 2026

• Ключ переехал на страницу «Для разработчиков» вместе со ссылкой на документацию API.

0.10.4 — 4 октября 2026

• Лимит частоты больше нельзя обойти выдуманным токеном или ключом: такие запросы считаются по адресу. Свой лимит остаётся у вошедших людей и у действующих ключей.

22 сентября 2026

• Новая платформа на production. Заявки на роль и на ключ API.

Как мы меняем API

• Внутри v1 — только совместимо. Могут появиться новые методы, необязательные параметры, новые поля в ответах и новые значения в списках вроде change или lessonType. Пишите клиент так, чтобы незнакомое поле или значение его не ломало.
• Сообщения об ошибках (error.message) могут меняться в любой момент; машинные коды (error.code) — нет.
• Несовместимое изменение — удаление метода или поля, смена смысла или формата — будет новой версией по новому адресу. О нём заранее напишем здесь и в «Что нового» приложения, а старая версия какое-то время будет работать рядом.
• Сначала d1. Всё новое сначала появляется на d1 и только потом, релизом раз в две недели, на production. Проверяйте интеграцию на d1 до релиза.

Что есть на вашем стенде

Пример читает OpenAPI стенда и говорит, сколько в нём методов, какие группы (теги) самые большие и включён ли на стенде «Вход через ВИШ»:

// What this stand's API offers: operations per tag and whether «Sign in with VISH» is on.
const API = process.env.VISH_API ?? 'https://d1.vish-app.ru/api/v1'

const response = await fetch(new URL('/documentation/json', API))
if (!response.ok) throw new Error(`OpenAPI: HTTP ${response.status}`)
const openapi = await response.json()

const perTag = new Map()
let total = 0
for (const [path, methods] of Object.entries(openapi.paths)) {
	if (path !== '/health' && !path.startsWith('/api/v1/')) throw new Error(`unversioned path ${path}`)
	for (const operation of Object.values(methods)) {
		total++
		for (const tag of operation.tags ?? []) perTag.set(tag, (perTag.get(tag) ?? 0) + 1)
	}
}
if (total === 0 || !perTag.has('schedule')) throw new Error('no schedule operations')

const discovery = await fetch(`${API}/oauth/.well-known/openid-configuration`)
console.log(`${openapi.info.title} ${openapi.info.version}: ${total} operations`)
console.log([...perTag].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([tag, count]) => `${tag} ${count}`).join(', '))
console.log('Sign in with VISH:', discovery.ok ? 'on' : `off (HTTP ${discovery.status})`)

Проверено: 2026-10, PWA aa337c45, platform bff65fce.