Публичный API

Общая информация

Публичный API можно использовать для создания скриптов и приложений, которые автоматизируют процессы, интегрируются с GitVerse, а также расширяют функциональность GitVerse.

Начало работы с публичным API

Интеграция с публичным API — это первый шаг к автоматизации, расширению возможностей и построению собственных решений на основе функциональности GitVerse. В этом руководстве вы узнаете, как получить доступ к API, авторизоваться, выполнить первый запрос и начать работать с репозиториями, настройками и другими сущностями.

Для начала работы вам потребуется настроить токен аутентификации: для этого перейдите в раздел Управления токенами. Создайте токен и сразу сохраните его, так как после того, как вы покинете страницу, он перестанет быть доступен. После этого вы можете взаимодействовать с публичным API, используя токен в качестве параметра HTTP-заголовка Authorization.

Authorization: Bearer YOUR_TOKEN 

HTTP Заголовки

Для работы с Public API GitVerse необходимо передавать обязательные HTTP-заголовки — они позволяют серверу корректно обработать запрос. В ответах API также могут присутствовать служебные заголовки для навигации, пагинации и управления данными.

Заголовки запроса

Authorization: Bearer YOUR_TOKEN

1. Обязательный заголовок.
2. Используется для аутентификации.
3. Вместо YOUR_TOKEN подставляется токен, полученный в настройках профиля.

Warning

Токен необходимо хранить в безопасном месте и не передавать его случайным образом. Он предоставляет доступ к вашему аккаунту GitVerse через API.

Accept: application/vnd.gitverse.object+json;version=1

1. Обязательный заголовок.
2. Указывает, что клиент ожидает JSON-ответ в формате, совместимом с GitVerse Public API.
3. Позволяет серверу правильно определить версию ответа.

Info

Мы используем кастомный MIME-тип application/vnd.gitverse+json, чтобы явно отделить ответы API от стандартных JSON-запросов. Это помогает избежать несовместимости при изменении формата данных.

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

Link

Заголовок Link используется для навигации по пагинированным ответам. Он позволяет удобно переходить между страницами результатов по сформированным URL-адресам.

Заголовок присутствует, если:

1. Присутствует в ответах эндпоинтов, поддерживающих пагинацию (параметры page и per_page).
2. Появляется только при успешном ответе (2xx).
3. Общее количество результатов превышает per_page.

Пример:

Link: <https://api.gitverse.ru/repos/owner/repo/issues?page=2>; rel="next",
      <https://api.gitverse.ru/repos/owner/repo/issues?page=1>; rel="first",
      <https://api.gitverse.ru/repos/owner/repo/issues?page=10>; rel="last"

rel	Описание
rel="prev"	Предыдущая страница (отсутствует на первой странице)
rel="next"	Следующая страница (отсутствует на последней странице)
rel="first"	Первая страница
rel="last"	Последняя страница

Tip

Для перехода между страницами рекомендуется использовать URL из заголовка Link, а не формировать параметры запроса вручную.

HTTP-методы

HTTP-метод эндпоинта определяет тип действия, которое он выполняет над указанным ресурсом. Некоторые из наиболее распространенных HTTP-методов: GET, POST, DELETE, PATCH и PUT. В документации к REST API для каждого эндпоинта указан используемый HTTP-метод.

Например, для эндпоинта «Список задач репозитория» используется метод GET.

В своих API мы стремимся использовать подходящие HTTP-методы для каждого действия.

Поддерживаемые HTTP-методы и их назначение:

Метод	Описание
GET	Используется для получения данных о ресурсах.
POST	Используется для создания новых ресурсов.
PATCH	Используется для частичного обновления свойств ресурса.
PUT	Используется для полного замещения ресурса или коллекции ресурсов.
DELETE	Используется для удаления ресурсов.

Список разделов

Настоящий подраздел документации предоставляет обзор всех доступных методов API GitVerse, сгруппированных по функциональности.

Использование Публичного API

Этот раздел API позволяет узнать, как работать с REST API GitVerse.

Политики стабильности API

1. Версионирование Этот механизм позволяет управлять изменениями в API, обеспечивая стабильность интеграций и предсказуемость поведения для всех пользователей.

2. Rate Limits Этот механизм защищает инфраструктуру от перегрузки и обеспечивает стабильную работу API для всех пользователей.

Пользователи

Этот раздел API позволяет управлять данными аутентифицированного пользователя.

Получение информации о пользователе

1. GET /user Возвращает информацию о текущем аутентифицированном пользователе.

2. GET /users/{username} Позволяет получить информацию о любом пользователе по его логину.

Работа с email-адресами

3. GET /user/emails Возвращает список email-адресов текущего пользователя.

4. POST /user/emails Добавляет один или несколько новых email-адресов текущему пользователю.

5. DELETE /user/emails Удаляет указанные email-адреса.

Получение списка репозиториев

6. GET /user/repos Возвращает все репозитории, доступные пользователю (личные и организации).

Поиск пользователей

7. GET /search/users Поиск пользователей по строке запроса (логину).

8. GET /user/{account_id} Возвращает информацию о пользователе по его числовому идентификатору (ID).

Команды

Этот раздел API позволяет работать с командами GitVerse.

Управление участниками и командами

1. GET /orgs/{org}/teams Возвращает список всех команд в указанной организации, которые видны авторизованному пользователю.

2. GET /orgs/{org}/teams/{team}/members Возвращает список всех участников указанной команды в организации.

3. GET /orgs/{org}/members/{username} Проверяет, состоит ли указанный пользователь в организации.

4. PUT /orgs/{org}/teams/{team}/repos/{owner}/{repo} Назначает или обновляет права команды на доступ к репозиторию.

Репозитории

Этот раздел API позволяет работать с репозиториями GitVerse.

Работа с репозиториями

1. GET /repos/{owner}/{repo}
   Возвращает основные данные о репозитории: название, владельца, настройки, права пользователя и т.д.

2. PATCH /repos/{owner}/{repo}
   Позволяет изменять ключевые параметры репозитория, такие как название, описание, приватность и поведение при слиянии веток.

3. POST /user/repos
   Создает новый репозиторий для пользователя.

4. DELETE /repos/{owner}/{repo}
   Удаляет указанный репозиторий.

Управление содержимым

5. GET /repos/{owner}/{repo}/branches
   Возвращает список всех веток репозитория с информацией о последнем коммите и защите веток.

6. GET /repos/{owner}/{repo}/contents/{path}
   Позволяет получить содержимое файла (в Base64) или список файлов внутри папки.

7. PUT /repos/{owner}/{repo}/contents/{filename}
   Создает новый файл или обновляет существующий в указанной ветке.

8. DELETE /repos/{owner}/{repo}/contents/{filename}
   Удаляет указанный файл из репозитория.

9. GET /repos/{owner}/{repo}/git/trees/{tree_sha}
   Возвращает структуру файлов и папок, связанную с указанным деревом Git.

Работа с коммитами

10. GET /repos/{username}/{reponame}/commits
    Возвращает список коммитов репозитория с возможностью фильтрации по ветке, пути, автору, дате и другим параметрам.

11. GET /repos/{username}/{reponame}/commits/{sha}
    Возвращает полную информацию о конкретном коммите, включая автора, сообщение, статистику изменений и список затронутых файлов.

12. GET /repos/{username}/{reponame}/compare/{basehead}
    Сравнивает две ветки, тега или коммита и возвращает разницу между ними (аналог git diff). Полезно для анализа изменений перед созданием запроса на слияние.

13. POST /repos/{username}/{reponame}/git/refs
    Создает новую git-ссылку (ветку, тег или кастомную ссылку) в репозитории.

14. GET /repos/{username}/{reponame}/git/matching-refs/{ref} Возвращает git-ссылку (ветку, тег или кастомную ссылку) по префиксу.

15. GET /repos/{username}/{reponame}/git/ref/{ref} Получает git-ссылку (ветку, тег или кастомную ссылку) по имени.

16. DELETE /repos/{username}/{reponame}/git/refs/{ref} Удаляет git-ссылку (ветку, тег или кастомную ссылку) .

Дополнительные методы

17. GET /repos/{owner}/{repo}/languages
    Возвращает список языков, используемых в репозитории, с указанием количества строк кода на каждом.

18. POST /repos/{owner}/{repo}/forks
    Создает форк репозитория для текущего пользователя.

19. PUT /repos/{owner}/{repo}/collaborators/{username}
    Добавляет пользователя как соавтора репозитория или обновляет его уровень доступа.

20. GET /orgs/{org}/repos
    Возвращает список репозиториев указанной организации с фильтрацией, сортировкой и пагинацией.

21. POST /orgs/{org}/repos Создает новый репозиторий в указанной организации от имени аутентифицированного пользователя.

Запросы на слияние

Этот раздел API описывает работу с запросами на слияние.

Работа с запросами на слияние

1. GET /repos/{owner}/{repo}/pulls/{pull_number}/files
   Возвращает список файлов, измененных в указанном запросе на слияние.

2. GET /repos/{owner}/{repo}/pulls/{pull_number}/commits
   Возвращает список коммитов, включенных в указанный запрос на слияние.

3. GET /repos/{owner}/{repo}/issues/{index} — получить запрос на слияние Возвращает подробную информацию о запросе на слияние по его индексу в репозитории.

4. POST /repos/{owner}/{repo}/pulls
   Создает новый запрос на слияние из указанной ветки в целевую.

5. PUT /repos/{owner}/{repo}/pulls/{pull_number}/update-branch
   Обновляет ветку запроса на слияние до актуального состояния целевой ветки.

6. PATCH /repos/{owner}/{repo}/pulls/{pull_number}
   Обновляет параметры существующего запроса на слияние: заголовок, описание, целевую ветку и разрешение на изменение ветки мейнтейнерами.

7. GET /repos/{owner}/{repo}/pulls
   Возвращает список запросов на слияние в указанном репозитории.

8. GET /repos/{owner}/{repo}/pulls/{pull_number}
   Возвращает подробную информацию о конкретном запросе на слияние по его номеру (pull_number).

9. GET /repos/{owner}/{repo}/pulls/{pull_number}/merge
   Проверяет статус слияния с базовой веткой.

Комментарии к запросам на слияние

10. GET /repos/{owner}/{repo}/issues/{index}/comments
    Возвращает список всех комментариев к запросу на слияние.

11. GET /repos/{owner}/{repo}/issues/comments/{id}
    Возвращает детали отдельного комментария по его уникальному идентификатору.

12. POST /repos/{owner}/{repo}/issues/{index}/comments
    Создает комментарий к запросу на слияние.

13. PATCH /repos/{owner}/{repo}/issues/{index}/comments/{comment_id}
    Редактирует комментарий.

14. DELETE /repos/{owner}/{repo}/issues/{index}/comments/{comment_id}
    Удаляет комментарий.

15. POST /repos/{owner}/{repo}/issues/{index}/comments/{comment_id}/reactions
    Добавляет реакцию на комментарий.

16. DELETE /repos/{owner}/{repo}/issues/{index}/comments/{comment_id}/reactions/{reaction_id}
    Удаляет реакцию.

Релизы

Этот раздел API позволяет работать с релизами GitVerse.

Работа с релизами

1. GET /repos/{owner}/{repo}/releases Возвращает список релизов в указанном репозитории с поддержкой пагинации и фильтрации по статусу (черновики, предварительные релизы).

2. POST /repos/{owner}/{repo}/releases Создает новый релиз на основе тега.

3. GET /repos/{owner}/{repo}/releases/{release_id} Возвращает информацию о релизе по его идентификатору.

4. DELETE /repos/{owner}/{repo}/releases/{release_id} Удаляет релиз по его идентификатору.

5. PATCH /repos/{owner}/{repo}/releases/{release_id} Редактирует информацию о релизе по его идентификатору.

6. GET /repos/{owner}/{repo}/releases/tags/{tag} Возвращает информацию о релизе по его тегу.

7. DELETE /repos/{owner}/{repo}/releases/tags/{tag} Удаляет релиз по его тегу.

Работа с ассетами

8. GET /repos/{owner}/{repo}/releases/{release_id}/assets Возвращает список ассетов релиза.

9. POST /repos/{owner}/{repo}/releases/{release_id}/assets Загружает ассет в релиз.

10. DELETE /repos/{owner}/{repo}/releases/{release_id}/assets/{asset_id} Удаляет ассет из релиза.

Избранное

Этот раздел API позволяет отмечать репозитории как избранные, а также проверять, добавлен ли репозиторий в список звезд у текущего пользователя.

Управление избранными репозиториями

1. GET /user/starred Возвращает список репозиториев, добавленных текущим пользователем в избранное. Поддерживается пагинация, сортировка и фильтрация результатов.

2. PUT /user/starred/{owner}/{repo} Добавляет указанный репозиторий в список отслеживаемых пользователем («ставит звезду»).

3. GET /user/starred/{owner}/{repo} Позволяет проверить, добавлен ли указанный репозиторий в список отслеживаемых у текущего пользователя.

4. DELETE /user/starred/{username}/{reponame} Удаляет указанный репозиторий из избранного текущего пользователя. При успешном удалении возвращается статус 204.

CI/CD

Этот раздел API позволяет работать с CI/CD GitVerse.

Ручной запуск потоков

1. GET /repos/{owner}/{repo}/actions/workflows/{workflow}/dispatches Возвращает список входных параметров, необходимых для ручного запуска указанного потока в репозитории.

2. POST /repos/{owner}/{repo}/actions/workflows/{workflow}/dispatches Запускает указанный поток вручную в репозитории.

Переменные организации

3. GET /orgs/{org}/actions/variables Возвращает список переменных организации.

4. POST /orgs/{org}/actions/variables Создает новую переменную в организации.

5. GET /orgs/{org}/actions/variables/{name} Получает конкретную переменную организации по ее имени.

6. DELETE /orgs/{org}/actions/variables/{name} Удаляет переменную организации по ее имени.

7. PATCH /orgs/{org}/actions/variables/{name} Обновляет переменную организации по ее имени.

Переменные репозитория

8. GET /repos/{owner}/{repo}/actions/variables Возвращает список переменных репозитория.

9. POST /repos/{owner}/{repo}/actions/variables Создает новую переменную в репозитории.

10. GET /repos/{owner}/{repo}/actions/variables/{name} Получает конкретную переменную репозитория по ее имени.

11. DELETE /repos/{owner}/{repo}/actions/variables/{name} Удаляет переменную репозитория по ее имени.

12. PATCH /repos/{owner}/{repo}/actions/variables/{name} Обновляет переменную репозитория по ее имени.

Секреты организации

13. GET /orgs/{org}/actions/secrets Получить список секретов организации.

14. GET /orgs/{org}/actions/secrets/{secret_name} Получить информацию о секрете организации.

15. PUT /orgs/{org}/actions/secrets/{secret_name} Создать или обновить секрет в организации.

16. DELETE /orgs/{org}/actions/secrets/{secret_name} Удалить секрет из организации.

Секреты репозитория

17. GET /repos/{owner}/{repo}/actions/secrets Получить список секретов репозитория.

18. GET /repos/{owner}/{repo}/actions/secrets/{secret_name} Получить информацию о секрете репозитория.

19. PUT /repos/{owner}/{repo}/actions/secrets/{secret_name} Создать или обновить секрет в репозитории.

20. DELETE /repos/{owner}/{repo}/actions/secrets/{secret_name} Удалить секрет из репозитория.

Локальные раннеры для организации

21. GET /orgs/{org}/actions/runners Получает список локальных раннеров для организации.

22. POST /orgs/{org}/actions/runners/registration-token Создает токен регистрации для раннера в организации.

23. GET /orgs/{org}/actions/runners/{runner_id} Получает информацию о конкретном раннере в организации.

24. DELETE /orgs/{org}/actions/runners/{runner_id} Удаляет раннер из организации.

Локальные раннеры для репозитория

25. GET /repos/{owner}/{repo}/actions/runners Получает список локальных раннеров для репозитория.

26. POST /repos/{owner}/{repo}/actions/runners/registration-token Создает токен регистрации для раннера в репозитории.

27. GET /repos/{owner}/{repo}/actions/runners/{runner_id} Получает информацию о конкретном раннере в репозитории.

28. DELETE /repos/{owner}/{repo}/actions/runners/{runner_id} Удаляет раннер из репозитория.

Артефакты

29. GET /repos/{owner}/{repo}/actions/artifacts Возвращает список артефактов (например, выходные данные сборки, пакеты или файлы развертывания) для указанного репозитория. Поддерживает пагинацию.

30. GET /repos/{owner}/{repo}/actions/artifacts/{artifact_id} Получает информацию о конкретном артефакте по его ID.

31. DELETE /repos/{owner}/{repo}/actions/artifacts/{artifact_id} Удаляет артефакт по его ID.

32. GET /repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip Перенаправляет на прямую ссылку для скачивания артефакта в виде ZIP-архива.

Вебхуки

Этот раздел API позволяет работать с вебхуками GitVerse.

Работа с вебхуками

1. GET /repos/{owner}/{repo}/hooks Получить список всех вебхуков для указанного репозитория.

2. POST /repos/{owner}/{repo}/hooks Создать новый вебхук для указанного репозитория.

3. GET /repos/{owner}/{repo}/hooks/{hook_id} Получить информацию о конкретном вебхуке.

4. PATCH /repos/{owner}/{repo}/hooks/{hook_id} Обновить информацию о вебхуке.

5. DELETE /repos/{owner}/{repo}/hooks/{hook_id} Удалить вебхук из репозитория.

Пакеты

Этот раздел API позволяет работать с пакетами GitVerse.

Пакеты пользователя

1. GET /users/{username}/packages/{package_type}/{package_name}/versions Получить список версий пакета пользователя.

2. DELETE /users/{username}/packages/{package_type}/{package_name}/versions/{package_version_id} Удалить конкретную версию пакета пользователя.

3. DELETE /users/{username}/packages/{package_type}/{package_name} Удалить пакет пользователя.

Пакеты организации

4. GET /orgs/{org}/packages/{package_type}/{package_name}/versions Получить список версий пакета организации.

5. DELETE /orgs/{org}/packages/{package_type}/{package_name}/versions/{package_version_id} Удалить конкретную версию пакета организации.

6. DELETE /orgs/{org}/packages/{package_type}/{package_name} Удалить пакет организации.

Соавторы

Работа с соавторами

Этот раздел API позволяет работать с соавторами репозитория.

1. GET/repos/{owner}/{repo}/collaborators Возвращает список всех соавторов (участников с доступом к репозиторию) указанного репозитория.

База данных Git

Этот раздел API позволяет узнать, как работать с низкоуровневыми методами для взаимодействия с внутренними объектами Git.

Деревья

1. POST /repos/{owner}/{repo}/git/trees Создает новое дерево (структуру файлов) в репозитории.

Коммиты

1. POST /repos/{owner}/{repo}/git/commits Создает новый объект коммита в репозитории.

GitVerse Lab

Этот раздел API описывает метод работы с GitVerse Lab.

Получение информации о задании GitVerse Lab

1. GET /assignments/{assignment_id}.

Возможные ошибки

Код	Описание
400 Bad Request	Некорректный формат запроса или параметров
401 Unauthorized	Необходима авторизация
403 Forbidden	Недостаточно прав
404 Not Found	Запрошенный ресурс не найден
406 Not Acceptable	Тип контента не поддерживается
409 Conflict	Конфликт (ресурс уже существует)
422 Unprocessable Entity	Ошибка валидации данных
429 Too Many Requests	Превышен лимит запросов
500 Internal Server Error	Внутренняя ошибка сервера
503 Service Unavailable	Сервис временно недоступен