Работа с 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);
}
}