Публичный 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

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

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

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

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

📌 Мы используем кастомный 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-методы и их назначение:

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

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

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

Этоn раздел 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 /repos/{owner}/{repo} Возвращает основные данные о репозитории: название, владельца, настройки, права пользователя и т.д.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

13. GET /repos/{owner}/{repo}/issues Возвращает список задач (issues) репозитория. На данный момент содержит только запросы на слияние (pull requests).

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

15. GET /repos/{owner}/{repo}/issues/{index} Возвращает подробную информацию о задаче (issue) или запросе на слияние (pull request) по его индексу в репозитории.

16. GET /repos/{owner}/{repo}/issues/{index}/comments
    Возвращает список всех комментариев, оставленных к задаче (issue) или запросу на слияние (pull request) с указанным индексом.

17. GET /repos/{owner}/{repo}/issues/{index}/labels Возвращает список меток (labels), назначенных на задачу (issue) или на запрос на слияние (pull request) с указанным индексом.

18. GET /repos/{owner}/{repo}/issues/{index}/timeline
    Возвращает хронологию всех событий и комментариев, связанных с задачей (issue) или с запросом на слияние (pull request).

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

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

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

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

Этот раздел API описывает как работать с запросами на влитике (PR).

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

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

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

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

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).

Команды

Этот раздел 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 позволяет отмечать репозитории как избранные, а также проверять, добавлен ли репозиторий в список звезд у текущего пользователя.

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

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

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

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

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

Соавторы репозитория

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

База данных Git

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

Релизы

Этот раздел 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} Удаляет ассет из релиза.

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-архива.

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