---
metadata:
  - name: generator
    content: Diplodoc Platform v5.70.2
  - property: og:type
    content: article
  - property: article:section
    content: Платформа плагинов
  - property: og:title
    content: Работа с API Вики
  - property: article:tag
    content: Техническая инструкция
alternate:
  - https://yandex.ru/dev/yandex-360/extensions/ru/tools/api/api-wiki.md
  - href: https://yandex.ru/dev/yandex-360/extensions/ru/tools/api/api-wiki.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.ru/dev/yandex-360/extensions/ru/llms.txt?revision=r22165285
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/yandex-360/extensions/ru/llms.txt?revision=r22165285


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

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

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

## Пакеты {#packages}

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

## Установка

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

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

## Базовое использование {#basic-usage}

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

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

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

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

### Path-, query- и body-параметры {#request-params}

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

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

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

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

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

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

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

## Разрешения {#permissions}

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

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

Например:

```json
{
    "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 |

## Найти поддержанную операцию {#supported-operations}

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

```typescript
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-типах означает, что клиент умеет сформировать запрос. Успех вызова также зависит от версии хоста, разрешений и прав пользователя.

## Загрузка файлов {#file-upload}

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

```typescript
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;
- разбиение исходного файла на части выполняет код плагина.

## Ответы и ошибки {#responses-and-errors}

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

```typescript
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`.

```typescript
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);
    }
}
```
