Работа с API Вики

Плагин может работать со страницами, таблицами, пользователями, загрузками и другими сущностями Вики через типизированный объект wikiApi. Запрос отправляется из iframe по bridge-методу api.wiki.call, а HTTP-вызов выполняет хост Вики. Прямой запрос к защищенному API из iframe не используется.

Доступ к каждой операции одновременно зависит от разрешений в манифесте и прав текущего пользователя.

Пакеты

Пакет Назначение
@weavix/wiki-api-plugin Типизированный клиент wikiApi для плагинов
@weavix/wiki-api-types Сгенерированные из OpenAPI типы операций, параметров и ответов; runtime-кода нет

Установка

npm install @weavix/wiki-api-plugin @weavix/wiki-api-types

Пакет @weavix/sdk-react уже содержит общий bridge через зависимость от @weavix/sdk-core.

Базовое использование

Импортируйте wikiApi:

import {wikiApi} from '@weavix/wiki-api-plugin';

Версия API выбирается через namespace .v1. В ключе метода не нужно повторять серверный префикс /public/v1:

const {data: page, headers} = await wikiApi.v1.get['/pages/{idx}']({
    pathParams: {idx: 42},
});

Path-, query- и body-параметры

Параметры запроса передаются в одном объекте:

  • pathParams — значения плейсхолдеров в пути;
  • queryParams — параметры query string;
  • bodyParams — JSON-тело запроса;
  • file — Blob или File для загрузки части файла.

Пример чтения дополнительных полей страницы:

const {data: page} = await wikiApi.v1.get['/pages/{idx}']({
    pathParams: {idx: 42},
    queryParams: {fields: 'breadcrumbs'},
});

Пример создания комментария:

const {data: comment} = await wikiApi.v1.post['/pages/{idx}/comments']({
    pathParams: {idx: 42},
    bodyParams: {body: 'Комментарий из плагина'},
});

TypeScript выводит обязательность и типы параметров из установленного пакета @weavix/wiki-api-types.

Разрешения

Разрешения на данные имеют формат wiki:<домен>:read|write. Домен — первый сегмент пути API:

  • для GET требуется действие read;
  • для POST, PUT, PATCH и DELETE требуется действие write.

Например:

{
    "permissions": {
        "data": [
            "wiki:pages:read",
            "wiki:pages:write"
        ]
    }
}

Поддерживаемые Wiki-разрешения:

Разрешение Назначение
wiki:pages:read Чтение страниц, потомков, доступов, вложений, комментариев и связанных с страницей данных
wiki:pages:write Создание, изменение и удаление страниц, доступов, вложений и комментариев
wiki:grids:read Чтение динамических таблиц
wiki:grids:write Создание и изменение таблиц, строк, столбцов и ячеек
wiki:users:read Чтение данных текущего пользователя
wiki:operations:read Чтение статуса асинхронных операций
wiki:upload_sessions:read Чтение состояния сессий загрузки
wiki:upload_sessions:write Создание, загрузка, завершение и отмена сессий
wiki:recovery_tokens:write Восстановление страницы по recovery token

Найти поддержанную операцию

Полный список методов не дублируется в документации. Используйте автодополнение после:

wikiApi.v1.get
wikiApi.v1.post
wikiApi.v1.put
wikiApi.v1.patch
wikiApi.v1.delete

Основные домены API:

  • /pages — страницы, доступы, ресурсы, вложения и комментарии;
  • /grids — динамические таблицы;
  • /users — пользователи;
  • /upload_sessions — составная загрузка файлов;
  • /operations — статусы асинхронных операций;
  • /recovery_tokens — восстановление страниц.

Наличие операции в TypeScript-типах означает, что клиент умеет сформировать запрос. Успех вызова также зависит от версии хоста, разрешений и прав пользователя.

Загрузка файлов

Большие файлы загружаются через upload session. Плагин создает сессию, самостоятельно делит файл на части и передает каждую часть как Blob.

const file = new File(['example'], 'example.txt', {
    type: 'application/octet-stream',
});

const {data: session} = await wikiApi.v1.post['/upload_sessions']({
    bodyParams: {
        file_name: file.name,
        file_size: file.size,
    },
});

await wikiApi.v1.put['/upload_sessions/{session_id}/upload_part']({
    pathParams: {session_id: session.session_id},
    queryParams: {part_number: 1},
    file,
});

await wikiApi.v1.post['/upload_sessions/{session_id}/finish']({
    pathParams: {session_id: session.session_id},
});

Для upload_part:

  • файл передается как raw application/octet-stream, без base64 и FormData;
  • bodyParams передавать нельзя;
  • номер части должен быть целым числом от 1 до 10 000;
  • разбиение исходного файла на части выполняет код плагина.

Ответы и ошибки

Успешный вызов возвращает:

type ApiResponse<T> = {
    data: T;
    headers: Record<string, string>;
};

Бинарный ответ возвращается как ArrayBuffer.

Ошибки приходят как PluginActionError:

  • VALIDATION_ERROR — некорректны версия, метод, путь, параметры или тело;
  • MISSING_REQUIRED_SCOPE — в манифесте нет необходимого разрешения;
  • числовой HTTP-статус — Wiki API вернул non-2xx ответ; детали находятся в errorData;
  • UNKNOWN_ERROR — сетевая ошибка или ошибка чтения/разбора ответа;
  • METHOD_NOT_SUPPORTED — хост не зарегистрировал api.wiki.call.
import {
    MISSING_REQUIRED_SCOPE,
    PluginActionError,
    VALIDATION_ERROR,
} from '@weavix/sdk-core';

try {
    await wikiApi.v1.get['/pages/{idx}']({
        pathParams: {idx: 42},
    });
} catch (error) {
    if (error instanceof PluginActionError) {
        console.error(error.code, error.message, error.errorData);
    }
}
Предыдущая
Следующая