Публичный API
Общая информация
Публичный API можно использовать для создания скриптов и приложений, которые автоматизируют процессы, интегрируются с GitVerse, а также расширяют функциональность GitVerse.
Начало работы с публичным API
Интеграция с публичным API — это первый шаг к автоматизации, расширению возможностей и построению собственных решений на основе функциональности GitVerse. В этом руководстве вы узнаете, как получить доступ к API, авторизоваться, выполнить первый запрос и начать работать с репозиториями, настройками и другими сущностями.
Для начала работы вам потребуется настроить токен аутентификации: для этого перейдите в раздел Управления токенами.
Создайте токен с отмеченным чекбоксом Публичное API и сразу сохраните его, т.к. после того, как вы покинете страницу, он перестанет быть доступен.
После этого вы можете взаимодействовать с публичным API, используя токен в качестве параметра HTTP-заголовка Authorization.
Authorization: Bearer YOUR_TOKEN HTTP Заголовки
При работе с Public API GitVerse необходимо указывать обязательные HTTP-заголовки, чтобы сервер мог корректно обработать ваш запрос.
Authorization: Bearer YOUR_TOKEN
- Обязательный заголовок.
- Используется для аутентификации.
- Вместо
YOUR_TOKENподставляется токен, полученный в настройках профиля.
⚠️ Токен необходимо хранить в безопасном месте и не передавать его случайным образом. Он предоставляет доступ к вашему аккаунту GitVerse через API.
Accept: application/vnd.gitverse.object+json;version=1
- Обязательный заголовок.
- Указывает, что клиент ожидает JSON-ответ в формате, совместимом с GitVerse Public API.
- Позволяет серверу правильно определить версию ответа.
📌 Мы используем кастомный MIME-тип
application/vnd.gitverse+json, чтобы явно отделить ответы API от стандартных JSON-запросов. Это помогает избежать несовместимости при изменении формата данных.
HTTP Методы
HTTP-метод эндпоинта определяет тип действия, которое он выполняет над указанным ресурсом. Некоторые из наиболее распространенных HTTP-методов: GET, POST, DELETE, PATCH и PUT. В документации к REST API для каждого эндпоинта указан используемый HTTP-метод.
Например, для эндпоинта «Список задач репозитория» используется метод GET.
В своих API мы стремимся использовать подходящие HTTP-методы для каждого действия — так же, как это делает GitHub REST API.
Поддерживаемые HTTP-методы и их назначение:
| Метод | Описание |
|---|---|
GET | Используется для получения данных о ресурсах. |
POST | Используется для создания новых ресурсов. |
PATCH | Используется для частичного обновления свойств ресурса. |
PUT | Используется для полного замещения ресурса или коллекции ресурсов. |
DELETE | Используется для удаления ресурсов. |
Список разделов
Настоящий подраздел документации предоставляет обзор всех доступных методов API GitVerse, сгруппированных по функциональности.
Использование Публичного API
Этоn раздел API позволяет узнать, как работать с REST API GitVerse.
Политики стабильности API
-
ВерсионированиеЭтот механизм позволяет управлять изменениями в API, обеспечивая стабильность интеграций и предсказуемость поведения для всех пользователей -
Rate LimitsЭтот механизм защищает инфраструктуру от перегрузки и обеспечивает стабильную работу API для всех пользователей.
Пользователи
Этот раздел API позволяет управлять данными аутентифицированного пользователя.
Получение информации о пользователе
-
GET /userВозвращает информацию о текущем аутентифицированном пользователе. -
GET /users/{username}Позволяет получить информацию о любом пользователе по его логину.
Работа с email-адресами
-
GET /user/emailsВозвращает список email-адресов текущего пользователя. -
POST /user/emailsДобавляет один или несколько новых email-адресов текущему пользователю. -
DELETE /user/emailsУдаляет указанные email-адреса.
Получение списка репозиториев
-
GET /user/reposВозвращает все репозитории, доступные пользователю (личные и организации). -
POST /user/reposСоздает новый репозиторий для пользователя.
Репозитории
Этот раздел API позволяет работать с репозиториями GitVerse.
Работа с репозиториями
-
GET /repos/{owner}/{repo}Возвращает основные данные о репозитории: название, владельца, настройки, права пользователя и т.д. -
PATCH /repos/{owner}/{repo}Позволяет изменять ключевые параметры репозитория, такие как название, описание, приватность и поведение при слиянии веток. -
POST /user/reposСоздает новый репозиторий для пользователя. -
DELETE /repos/{owner}/{repo}Удаляет указанный репозиторий.
Управление содержимым
-
GET /repos/{owner}/{repo}/contents/{path}Позволяет получить содержимое файла (в Base64) или список файлов внутри папки. -
PUT /repos/{owner}/{repo}/contents/{filename}Создает новый файл или обновляет существующий в указанной ветке. -
DELETE /repos/{owner}/{repo}/contents/{filename}Удаляет указанный файл из репозитория. -
GET /repos/{owner}/{repo}/git/trees/{tree_sha}Возвращает структуру файлов и папок, связанную с указанным деревом Git.
Работа с коммитами
-
GET /repos/{username}/{reponame}/commitsВозвращает список коммитов репозитория с возможностью фильтрации по ветке, пути, автору, дате и другим параметрам. -
GET /repos/{username}/{reponame}/commits/{sha}Возвращает полную информацию о конкретном коммите, включая автора, сообщение, статистику изменений и список затронутых файлов. -
GET /repos/{username}/{reponame}/compare/{basehead}Сравнивает две ветки, тега или коммита и возвращает разницу между ними (аналогgit diff). Полезно для анализа изменений перед созданием запроса на слияние. -
POST /repos/{username}/{reponame}/git/refsСоздает новую Git-ссылку (ветку, тег или кастомную ссылку) в репозитории.
Дополнительные методы
-
GET /repos/{owner}/{repo}/issuesВозвращает список задач (issues) репозитория. На данный момент содержит только запросы на слияние (pull requests). -
GET /repos/{owner}/{repo}/issues/comments/{id}Возвращает детали отдельного комментария по его уникальному идентификатору (id). -
GET /repos/{owner}/{repo}/issues/{index}Возвращает подробную информацию о задаче (issue) или запросе на слияние (pull request) по его индексу в репозитории. -
GET /repos/{owner}/{repo}/issues/{index}/comments
Возвращает список всех комментариев, оставленных к задаче (issue) или запросу на слияние (pull request) с указанным индексом. -
GET /repos/{owner}/{repo}/issues/{index}/labelsВозвращает список меток (labels), назначенных на задачу (issue) или на запрос на слияние (pull request) с указанным индексом. -
GET /repos/{owner}/{repo}/issues/{index}/timeline
Возвращает хронологию всех событий и комментариев, связанных с задачей (issue) или с запросом на слияние (pull request). -
GET /repos/{owner}/{repo}/languagesВозвращает список языков, используемых в репозитории, с указанием количества строк кода на каждом. -
POST /repos/{owner}/{repo}/forksСоздает форк репозитория для текущего пользователя. -
PUT /repos/{owner}/{repo}/collaborators/{username}Добавляет пользователя как соавтора репозитория или обновляет его уровень доступа.
Запросы на слияние
Этот раздел API описывает как работать с запросами на влитике (PR).
Работа с запросами на слияние
-
GET /repos/{owner}/{repo}/pulls/{pull_number}/filesВозвращает список файлов, измененных в указанном запросе на слияние. -
GET /repos/{owner}/{repo}/pulls/{pull_number}/commitsВозвращает список коммитов, включенных в указанный запрос на слияние -
GET /repos/{owner}/{repo}/branchesВозвращает список всех веток репозитория с информацией о последнем коммите и защите веток. -
POST /repos/{owner}/{repo}/pullsСоздает новый запрос на слияние из указанной ветки в целевую. -
PUT /repos/{owner}/{repo}/pulls/{pull_number}/update-branchСоздает новый запрос на слияние из указанной ветки в целевую. -
PATCH /repos/{owner}/{repo}/pulls/{pull_number}Обновляет параметры существующего запроса на слияние: заголовок, описание, целевую ветку и разрешение на изменение ветки мейнтейнерами. -
GET /repos/{owner}/{repo}/pullsВозвращает список запросов на слияние в указанном репозитории. -
GET /repos/{owner}/{repo}/pulls/{pull_number}Возвращает подробную информацию о конкретном запросе на слияние по его номеру (pull_number).
Команды
Этот раздел API позволяет работать с командами GitVerse.
Управление участниками и командами
-
GET /orgs/{org}/teamsВозвращает список всех команд в указанной организации, которые видны авторизованному пользователю. -
GET /orgs/{org}/teams/{team}/membersВозвращает список всех участников указанной команды в организации. -
GET /orgs/{org}/members/{username}Проверяет, состоит ли указанный пользователь в организации. -
PUT /orgs/{org}/teams/{team}/repos/{owner}/{repo}Назначает или обновляет права команды на доступ к репозиторию.
Звезды
Этот раздел API позволяет отмечать репозитории как избранные, а также проверять, добавлен ли репозиторий в список звезд у текущего пользователя.
Управление избранными репозиториями
-
GET /user/starredВозвращает список репозиториев, добавленных текущим пользователем в избранное. Поддерживается пагинация, сортировка и фильтрация результатов. -
PUT /user/starred/{owner}/{repo}Добавляет указанный репозиторий в список отслеживаемых пользователем («ставит звезду»). -
GET /user/starred/{owner}/{repo}Позволяет проверить, добавлен ли указанный репозиторий в список отслеживаемых у текущего пользователя. -
DELETE /user/starred/{username}/{reponame}Удаляет указанный репозиторий из избранного текущего пользователя. При успешном удалении возвращается статус 204.
Соавторы репозитория
GET/repos/{owner}/{repo}/collaboratorsВозвращает список всех соавторов (участников с доступом к репозиторию) указанного репозитория.
База данных Git
POST /repos/{owner}/{repo}/git/treesСоздает новое дерево (структуру файлов) в репозитории.POST /repos/{owner}/{repo}/git/commitsСоздает новый объект коммита в репозитории.
Релизы
Этот раздел API позволяет работать с релизами GitVerse.
Работа с релизами
-
GET /repos/{owner}/{repo}/releasesВозвращает список релизов в указанном репозитории с поддержкой пагинации и фильтрации по статусу (черновики, предварительные релизы). -
POST /repos/{owner}/{repo}/releasesСоздает новый релиз на основе тега. -
GET /repos/{owner}/{repo}/releases/{release_id}Возвращает информацию о релизе по его идентификатору. -
DELETE /repos/{owner}/{repo}/releases/{release_id}Удаляет релиз по его идентификатору. -
PATCH /repos/{owner}/{repo}/releases/{release_id}Редактирует информацию о релизе по его идентификатору. -
GET /repos/{owner}/{repo}/releases/tags/{tag}Возвращает информацию о релизе по его тегу. -
DELETE /repos/{owner}/{repo}/releases/tags/{tag}Удаляет релиз по его тегу.
Работа с ассетами
-
GET /repos/{owner}/{repo}/releases/{release_id}/assetsВозвращает список ассетов релиза. -
POST /repos/{owner}/{repo}/releases/{release_id}/assetsЗагружает ассет в релиз. -
DELETE /repos/{owner}/{repo}/releases/{release_id}/assets/{asset_id}Удаляет ассет из релиза.
CI/CD
Этот раздел API позволяет работать с CI/CD GitVerse.
Ручной запуск потоков
-
GET /repos/{owner}/{repo}/actions/workflows/{workflow}/dispatchesВозвращает список входных параметров, необходимых для ручного запуска указанного потока в репозитории. -
POST /repos/{owner}/{repo}/actions/workflows/{workflow}/dispatchesЗапускает указанный поток вручную в репозитории.
Переменные организации
-
GET /orgs/{org}/actions/variablesВозвращает список переменных организации. -
POST /orgs/{org}/actions/variablesСоздает новую переменную в организации. -
GET /orgs/{org}/actions/variables/{name}Получает конкретную переменную организации по ее имени. -
DELETE /orgs/{org}/actions/variables/{name}Удаляет переменную организации по ее имени. -
PATCH /orgs/{org}/actions/variables/{name}Обновляет переменную организации по ее имени.
Переменные репозитория
-
GET /repos/{owner}/{repo}/actions/variablesВозвращает список переменных репозитория. -
POST /repos/{owner}/{repo}/actions/variablesСоздает новую переменную в репозитории. -
GET /repos/{owner}/{repo}/actions/variables/{name}Получает конкретную переменную репозитория по ее имени. -
DELETE /repos/{owner}/{repo}/actions/variables/{name}Удаляет переменную репозитория по ее имени. -
PATCH /repos/{owner}/{repo}/actions/variables/{name}Обновляет переменную репозитория по ее имени.
Секреты организации
-
GET /orgs/{org}/actions/secretsПолучить список секретов организации. -
GET /orgs/{org}/actions/secrets/{secret_name}Получить информацию о секрете организации. -
PUT /orgs/{org}/actions/secrets/{secret_name}Создать или обновить секрет в организации. -
DELETE /orgs/{org}/actions/secrets/{secret_name}Удалить секрет из организации.
Секреты репозитория
-
GET /repos/{owner}/{repo}/actions/secretsПолучить список секретов репозитория. -
GET /repos/{owner}/{repo}/actions/secrets/{secret_name}Получить информацию о секрете репозитория. -
PUT /repos/{owner}/{repo}/actions/secrets/{secret_name}Создать или обновить секрет в репозитории. -
DELETE /repos/{owner}/{repo}/actions/secrets/{secret_name}Удалить секрет из репозитория.
Локальные раннеры для организации
-
GET /orgs/{org}/actions/runnersПолучает список локальных раннеров для организации. -
POST /orgs/{org}/actions/runners/registration-tokenСоздает токен регистрации для раннера в организации. -
GET /orgs/{org}/actions/runners/{runner_id}Получает информацию о конкретном раннере в организации. -
DELETE /orgs/{org}/actions/runners/{runner_id}Удаляет раннер из организации.
Локальные раннеры для репозитория
-
GET /repos/{owner}/{repo}/actions/runnersПолучает список локальных раннеров для репозитория. -
POST /repos/{owner}/{repo}/actions/runners/registration-tokenСоздает токен регистрации для раннера в репозитории. -
GET /repos/{owner}/{repo}/actions/runners/{runner_id}Получает информацию о конкретном раннере в репозитории. -
DELETE /repos/{owner}/{repo}/actions/runners/{runner_id}Удаляет раннер из репозитория.
Артефакты
-
GET /repos/{owner}/{repo}/actions/artifactsВозвращает список артефактов (например, выходные данные сборки, пакеты или файлы развертывания) для указанного репозитория. Поддерживает пагинацию. -
GET /repos/{owner}/{repo}/actions/artifacts/{artifact_id}Получает информацию о конкретном артефакте по его ID. -
DELETE /repos/{owner}/{repo}/actions/artifacts/{artifact_id}Удаляет артефакт по его ID. -
GET /repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zipПеренаправляет на прямую ссылку для скачивания артефакта в виде ZIP-архива.
Возможные ошибки
| Код | Описание |
|---|---|
400 Bad Request | Некорректный формат данных |
401 Unauthorized | Необходима авторизация |
403 Forbidden | Недостаточно прав |
404 Not Found | Репозиторий не найден |
406 Not Acceptable | Тип контента не поддерживается |
500 Internal Server Error | Внутренняя ошибка сервера |