API трекера

На какие запросы REST API распространённого трекера отвечает Kaiku и где ведёт себя иначе.

Что это

Kaiku отвечает на REST API самостоятельно устанавливаемой версии самого распространённого корпоративного трекера: те же пути, тела запросов, формы ответов, коды и формат ошибок. Инструмент, написанный под него, направляют на адрес воркспейса с токеном — и он работает.

Мы никак не связаны с поставщиком того трекера, и совместимость — это то, над чем мы работаем, а не гарантия для любого инструмента. Если нужный вам инструмент ведёт себя не так — скажите нам: для нас это ошибка.

GET /rest/api/2/serverInfo отвечает без входа и называет развёртывание серверным. По нему инструменты решают, как разговаривать, и по нему же быстро проверить, что адрес верный.

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

Всё ниже — под /rest/api/2, если не сказано иное.

Область	Запросы
Вы и сервер	`myself`, `serverInfo`, `configuration`, `field`, `mypermissions`
Проекты	`project`, `project/search`, `project/{key}` с `/statuses`, `/versions`, `/components`; создание, изменение и удаление проекта
Задачи	`issue` — создать, прочитать, изменить, удалить; `issue/{key}/assignee`; `issue/createmeta`, `issue/{key}/editmeta`
Процесс	`issue/{key}/transitions` — список и переход
Комментарии	`issue/{key}/comment` — список, добавить, изменить, удалить
Учёт времени	`issue/{key}/worklog` — список и запись
Файлы	`issue/{key}/attachments` — загрузить; `attachment/{id}` — прочитать и удалить; `/secure/attachment/{id}/{filename}` — скачать
Связи и наблюдатели	`issueLink`, `issueLinkType`, `issue/{key}/remotelink`, `issue/{key}/watchers`
Поиск	`search` и `search/jql`, GET и POST, под `/rest/api/2` и `/rest/api/3` — см. Поиск (JQL)
Справочники	`issuetype`, `status`, `statuscategory`, `priority`, `resolution`
Люди	`user`, `user/search`, `user/assignable/search`, `user/assignable/multiProjectSearch`, `users/search`
Доски и спринты	Под `/rest/agile/1.0`: `board` с `configuration`, `sprint`, `issue`, `backlog`, `epic`; создать, начать, завершить и удалить спринт; перенести задачи в спринт и обратно в бэклог

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

`/rest/api/3` почти нет. Там отвечают только myself, search, search/jql и remotelink. Используйте /rest/api/2 — инструменты для самостоятельно устанавливаемой версии так и делают.
Форматированный текст — строка. Описания и комментарии — обычный текст, Markdown или вики-разметка трекера, туда и обратно строкой. Описание, присланное объектом-документом (формат облачной версии), не читается.
Нет вовсе: сохранённых фильтров, дашбордов, групп, пакетного создания задач и истории изменений (expand=changelog).
Версии и компоненты приходят пустыми, создать их нельзя.
Проект или задача, которые вам не видны, — это 404, а не 403.
Архивные задачи в поиск не попадают, если запрос не упоминает archived.
Story points — это customfield_10016, спринт — customfield_10020, как ждут инструменты трекера. Столбцы, которые проект завёл сам, — customfield_2xxxx; их перечисляет GET field.

Страницы, ошибки и кэш

Поиск листается через startAt и maxResults и возвращает total (все совпадения) и isLast. maxResults по умолчанию 50, не больше 1000.
Ошибки в форме трекера: {"errorMessages": […], "errors": {…}}. Текст по-английски, если запрос не прислал Accept-Language.
Каждый JSON-ответ на GET несёт ETag; пришлите его обратно в If-None-Match — и неизменившийся ответ придёт как 304 без тела.
Файл — до 100 МБ. Описание или комментарий — до 100 КБ текста; длиннее получает 400 и никогда не обрезается.
В метках не бывает пробелов.

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