Интеграционный API¶

Обзор¶

REST API Системы предоставляет программный интерфейс для автоматизации рабочих процессов и интеграции с внешними приложениями через стандартные HTTP-методы и формат JSON.

С помощью REST API можно:

Управлять ресурсами Системы в большом объёме без выполнения ручных операций.
Интегрировать данные Системы в собственные приложения для совместной работы.
Управлять процессами CI/CD сразу в нескольких проектах.
Программно управлять доступом пользователей.

Формирование запроса REST API¶

Запрос состоит из:

Корневого эндпоинта — имени хоста экземпляра Системы.
Пути запроса с префиксом /api/v4 (четвёртая версия API).

Пример получения списка проектов:

curl --request GET \
  --url "https://appseccode.example.ru/api/v4/projects"

Для некоторых эндпоинтов требуется аутентификация.

Ограничение частоты запросов¶

Запросы к REST API подчиняются ограничениям частоты (rate limits), которые предотвращают перегрузку Системы.

Формат ответа¶

Ответы возвращаются в формате JSON. Некоторые эндпоинты поддерживают также обычный текст (plain text). Для каждого эндпоинта существует свой список поддерживаемых форматов.

Требования к запросу¶

Тело запроса¶

Параметры запроса передаются одним из двух способов:

В query string запроса GET:

curl --request POST \
  --url "https://appseccode.example.ru/api/v4/projects?name=<example-name>&description=<example-description>"

В теле запроса POST или PUT в формате JSON:

curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"name":"<example-name>", "description":"<example-description>"}' \
  "https://appseccode.example.ru/api/v4/projects"

Примечание

Query string в URL-кодированном виде имеет ограничение по длине. При его превышении возвращается ошибка 414 Request-URI Too Large — в таком случае следует передавать параметры в теле запроса.

Параметры пути¶

В описании эндпоинта параметры пути обозначаются двоеточием (например, :id и :group_id). Само двоеточие в URL включать не нужно — оно используется только для обозначения параметра в документации.

Пример описания эндпоинта:

DELETE /projects/:id/share/:group_id

Пример запроса для проекта с идентификатором 5 и группы с идентификатором 17:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://appseccode.example.ru/api/v4/projects/5/share/17"

Параметры пути необходимо URL-кодировать. Несоответствие формата приводит к ответу с кодом 404.

Поля `id` и `iid`¶

Поле	Описание
`id`	Уникальный идентификатор объекта в рамках всех проектов Системы.
`iid`	Внутренний идентификатор, отображаемый в веб-интерфейсе. Уникален в пределах одного проекта.

Если ресурс имеет как поле iid, так и поле id, поле iid обычно используется вместо id, чтобы получить ресурс.

Пример: для проекта id=42, обсуждения id=46, iid=5:

Корректный запрос: GET /projects/42/issues/5.
Некорректный запрос: GET /projects/42/issues/46.

Кодирование¶

При выполнении запроса REST API часть содержимого должна быть закодирована для учета специальных символов и структур данных.

Пути с пространством имён¶

Путь вида NAMESPACE/PROJECT_PATH обязательно URL-кодируется: символ / заменяется на %2F.

Пример:

GET /api/v4/projects/diaspora%2Fdiaspora

Примечание

Путь проекта (path) отличается от его имени (name). Найти путь можно в URL проекта или в разделе Настройки → Общие → Расширенные → Изменить путь.

Пути файлов, имена веток и тегов¶

Если значение содержит /, символы необходимо кодировать как %2F:

GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master
GET /api/v4/projects/1/branches/my%2Fbranch/commits
GET /api/v4/projects/1/repository/tags/my%2Ftag

Параметры типа array¶

Параметры-массивы передаются повторением имени с суффиксом []. Пример с массивом import_sources:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  -d "import_sources[]=github" \
  -d "import_sources[]=bitbucket" \
  --url "https://appseccode.example.ru/api/v4/some_endpoint"

Параметры типа hash¶

Параметры-хеши передаются через имена с указанием ключей в квадратных скобках. Пример с хешем override_params:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "namespace=email" \
  --form "path=impapi" \
  --form "file=@/path/to/somefile.txt" \
  --form "override_params[visibility]=private" \
  --form "override_params[some_other_param]=some_value" \
  --url "https://appseccode.example.ru/api/v4/projects/import"

Массивы хешей¶

Пример с массивом хешей variables, передаваемых в query string:

curl --globoff --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://appseccode.example.ru/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world"

Тот же запрос с телом в формате JSON:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \
  --url "https://appseccode.example.ru/api/v4/projects/169/pipeline"

Даты в формате ISO 8601 со знаком «+»¶

Символ + в URL интерпретируется как пробел. Чтобы передать дату вида 2017-10-17T23:11:13.000+05:30, экранируйте + как %2B:

2017-10-17T23:11:13.000%2B05:30

Обработка ответа¶

В некоторых случаях ответ API может отличаться от ожидаемого. Проблемы могут включать пустые значения и перенаправление.

Значения `null` и `false`¶

В ответах API логические (булевы) поля могут возвращаться со значением null. При обработке ответа значение null следует считать эквивалентным false.

В аргументах запроса логические параметры передаются только как true или false — значение null не используется.

Перенаправления¶

После изменения пути проекта REST API может вернуть сообщение о его перемещении. В этом случае используйте новый URL из заголовка Location ответа.

Пример запроса для перемещённого проекта:

curl --request GET \
  --verbose \
  --url "https://appseccode.example.ru/api/v4/projects/appseccode-group%2Fold-path-project"

Ответ:

< Location: http://appseccode.example.ru/api/v4/projects/81
...
This resource has been moved permanently to https://appseccode.example.ru/api/v4/projects/81

Пагинация¶

Пагинация по смещению (offset-based)¶

Используется по умолчанию.

Параметр	Описание
`page`	Номер страницы (по умолчанию: 1).
`per_page`	Количество элементов на странице (по умолчанию: 20, максимум: 100).

Пример запроса с выводом 50 пространств имён на странице:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://appseccode.example.ru/api/v4/namespaces?per_page=50"

Примечание

Для пагинации по смещению действует максимально допустимое значение смещения. Это значение можно изменить в локальном экземпляре Системы.

Заголовок `Link`¶

В заголовках ответа возвращается Link со ссылками prev, next, first, last. Обязательно используйте эти ссылки вместо создания собственных URL-адресов.

Пример запроса (по 3 элемента на странице per_page=3, страница 2 page=2, комментарии обсуждения id=8 проекта id=9):

curl --request GET \
  --head \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://appseccode.example.ru/api/v4/projects/9/issues/8/notes?per_page=3&page=2"

Заголовки ответа:

HTTP/2 200 OK
cache-control: no-cache
content-length: 1103
content-type: application/json
date: Mon, 18 Jan 2016 09:43:18 GMT
link: <https://appseccode.example.ru/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://appseccode.example.ru/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://appseccode.example.ru/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://appseccode.example.ru/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
status: 200 OK
vary: Origin
x-next-page: 3
x-page: 2
x-per-page: 3
x-prev-page: 1
x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86
x-runtime: 0.108688
x-total: 8
x-total-pages: 3

Дополнительные заголовки пагинации¶

Заголовок	Описание
`x-next-page`	Индекс следующей страницы.
`x-page`	Индекс текущей страницы (нумерация начинается с 1).
`x-per-page`	Количество элементов на странице.
`x-prev-page`	Индекс предыдущей страницы.
`x-total`	Общее количество элементов.
`x-total-pages`	Общее количество страниц.

Пагинация по курсору (keyset-based)¶

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

Параметр	Обязательность	Описание
`pagination`	Да	Должен иметь значение `keyset`.
`per_page`	Нет	Количество элементов на странице (по умолчанию: 20, максимум: 100).
`order_by`	Да	Столбец, по которому выполняется сортировка.
`sort`	Да	Направление сортировки: `asc` или `desc`.

Пример запроса 50 проектов с сортировкой по id в возрастающем порядке:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://appseccode.example.ru/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"

Ответ:

HTTP/1.1 200 OK
...
Link: <https://appseccode.example.ru/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
Status: 200 OK
...

Ссылка на следующую страницу содержит дополнительный фильтр id_after=42, исключающий уже извлеченные записи.

Следующий пример запроса групп перечисляет 50 групп на страницу, упорядоченных с сортировкой по имени:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://appseccode.example.ru/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc"

Заголовок ответа включает ссылку на следующую страницу:

HTTP/1.1 200 OK
...
Link: <https://appseccode.example.ru/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc&cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9>; rel="next"
Status: 200 OK
...

Ссылка на следующую страницу содержит дополнительный фильтр cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9, который исключает уже полученные записи.

Дополнительные заголовки с курсорами:

X-NEXT-CURSOR — курсор для следующей страницы.
X-PREV-CURSOR — курсор для предыдущей страницы (если доступна).

Тип фильтра зависит от используемой опции order_by, вы можете иметь более одного дополнительного фильтра.

Примечание

Используйте только ссылки, возвращаемые Системой в заголовке Link, — не формируйте URL-адреса с курсорами вручную.

Ресурсы, поддерживающие пагинацию по курсору¶

Ресурс	Параметры	Доступность
События аудита группы	`order_by=id`, `sort=desc`	Только для аутентифицированных пользователей.
Группы	`order_by=name`, `sort=asc`	Только для неаутентифицированных пользователей.
События аудита экземпляра	`order_by=id`, `sort=desc`	Только для аутентифицированных пользователей.
Конвейеры пакета	`order_by=id`, `sort=desc`	Только для аутентифицированных пользователей.
Задания проекта	`order_by=id`, `sort=desc`	Только для аутентифицированных пользователей.
События аудита проекта	`order_by=id`, `sort=desc`	Только для аутентифицированных пользователей.
Проекты	`order_by=id`	Все пользователи.
Пользователи	`order_by=id`, `order_by=name`, `order_by=username`, `order_by=created_at`, `order_by=updated_at`	Все пользователи.
Теги Registry Repository	`order_by=name`, `sort=asc`, `sort=desc`	Только для аутентифицированных пользователей.
Список дерева репозитория	Не применяется.	Все пользователи.
Обсуждения проекта	`order_by=created_at`, `order_by=updated_at`, `order_by=title`, `order_by=id`, `order_by=weight`, `order_by=due_date`, `order_by=relative_position`, `sort=asc`, `sort=desc`	Все пользователи.

Поведение заголовков при больших ответах¶

Если результат запроса содержит более 10 000 записей, Система не возвращает следующие заголовки:

x-total;
x-total-pages;
ссылку rel="last" в заголовке Link.

Версионирование и устаревание¶

Версия REST API Системы соответствует спецификации семантического версионирования. Текущая мажорная версия — 4.

Политика версионирования:

Если минорная версия не указана явно, эндпоинт считается стабильным.
Новые функциональные возможности добавляются в рамках той же мажорной версии.
Изменения мажорной версии синхронизируются с мажорными релизами Системы.

Из политики устаревания исключаются:

Элементы, помеченные как experimental или beta в описании ресурсов REST API.
Поля, доступные за функциональными флагами (feature flags), которые отключены по умолчанию.

Интеграционный API¶

Обзор¶

Формирование запроса REST API¶

Ограничение частоты запросов¶

Формат ответа¶

Требования к запросу¶

Тело запроса¶

Параметры пути¶

Поля id и iid¶

Кодирование¶

Пути с пространством имён¶

Пути файлов, имена веток и тегов¶

Параметры типа array¶

Параметры типа hash¶

Массивы хешей¶

Даты в формате ISO 8601 со знаком «+»¶

Обработка ответа¶

Значения null и false¶

Перенаправления¶

Пагинация¶

Пагинация по смещению (offset-based)¶

Заголовок Link¶

Дополнительные заголовки пагинации¶

Пагинация по курсору (keyset-based)¶

Ресурсы, поддерживающие пагинацию по курсору¶

Поведение заголовков при больших ответах¶

Версионирование и устаревание¶

Поля `id` и `iid`¶

Значения `null` и `false`¶

Заголовок `Link`¶