API вики

Вики говорит на REST API распространённой корпоративной вики: на что отвечает, что хранит и какой у неё язык запросов.

Что это

У каждого проекта ровно одно пространство вики, и его ключ совпадает с ключом проекта. Вики отвечает на REST API самостоятельно устанавливаемой версии распространённой корпоративной вики по адресу https://<workspace>.kaiku.tech/rest/api/… — и те же запросы под /wiki/rest/api/… для инструментов, которые ждут облачную раскладку. Токен тот же — см. Подключение инструмента.

Ошибки — в форме той вики, она отличается от формы трекера. Страница, которую вам не видно, — 404; 403 значит, что видеть можно, а менять нельзя.

На что отвечает

Область	Запросы
Страницы	`content` — список, создать, прочитать (и старую версию через `?version=N`), изменить, удалить; `content/{id}/child`, `/descendant/page`, `/ancestor`, `/history`, `/version`; `content/{id}/move/{append\|above\|below}/{target}`
Комментарии	`content/{id}/child/comment`, с ответами и комментариями к фрагменту; создаются через `POST content` с `type: "comment"`
Файлы	`content/{id}/child/attachment` — загрузить, список, заменить; `content/att{id}`; `/download/attachments/{pageId}/{filename}`
Метки	`content/{id}/label` — список, добавить, убрать
Ограничения	`content/{id}/restriction` — кто может читать и кто может править страницу
Пространства	`space`, `space/{key}`, `space/{key}/content`
Поиск	`search` и `content/search` с `cql` — см. ниже
Люди	`user/current`, `user`, `search/user`, `group`
Выгрузка	`exportword?pageId=…` — страница как документ Word

Списки листаются через start и limit (по умолчанию 25, не больше 200) и приходят в постраничной обёртке с results, size и _links. expand работает, как в оригинале.

Каким может быть текст страницы

storage — XHTML-формат хранения вики, сохраняется как прислан.
markdown — при сохранении превращается в storage. Заголовки, списки, таблицы, ссылки, код и формулы в $…$ и $$…$$.
wiki — тоже читается как Markdown, а не как исходная вики-разметка.
Объект-документ (atlas_doc_format) не преобразуется: не присылайте его.

Каждое сохранение — новая версия. Изменение должно нести следующий номер версии: номер, не больший текущего, получает 409 — кто-то сохранил страницу между делом; перечитайте её и повторите.

Страница — до 512 КБ текста, комментарий — до 100 КБ, файл — до 100 МБ. Файл с именем, которое у страницы уже есть, заменяет прежний новой версией.

Чем отличается

Только страницы и комментарии: ни блогов, ни досок, ни баз данных. Создание другого типа — 400.
Свойства содержимого всегда пусты.
Сравнения версий нет: получите обе через ?version=N и сравните сами.
У поиска нет оценки релевантности: без сортировки первыми идут недавно изменённые.
Главную страницу пространства нельзя удалить или ограничить.
Созданная страница отвечает 200, а не 201.

Поиск (CQL)

Поле	С чем сравнивается
`space` (или `space.key`)	ключ пространства
`type`	`page`
`title`	название
`text`	название, текст, метки — и слова на схемах, приложенных как SVG
`label`	любая одна метка
`creator`	имя пользователя, создавшего страницу
`contributor`	имя пользователя, правившего её последним, — а не всех, кто когда-либо правил
`ancestor`	id страницы где угодно выше
`parent`	id страницы непосредственно выше
`id`	id страницы
`created`, `lastmodified`	дата

Операторы: =, !=, ~ (содержит, без учёта регистра), !~, IN, NOT IN и >, >=, <, <= для дат.
AND, OR, скобки. NOT нет.
Функции: currentUser(), startOfDay() и now("-7d") — с m для минут, h, d, w и y.
ORDER BY created, lastmodified, title, space или id, при желании с DESC.
Не понимаются: favourite, watcher, mention, macro, container и NOT перед группой.

Как и поиск трекера, CQL-запрос никогда не отвергается: поле, которого нет в таблице выше, пропускается и подходит любой странице.

Чего-то не хватает или всё не так, как здесь написано? Напишите на hello@kaiku.tech