23. GET /repos/{username}/{reponame}/git/matching-refs/{ref} — поиск git-ссылок по префиксу

Описание

Выполняет поиск git-ссылок репозитория, имена которых начинаются с переданного префикса. Используется для:

• получения списка всех веток с определенным префиксом (например, всех feature-веток);
• поиска тегов по версии (например, всех тегов v2.*);
• получения всех ссылок репозитория, если параметр ref опущен.

Совпадение работает по префиксу — например, запрос heads/feature вернет ветки feature/auth и feature/billing, но не hotfix-feature. Если совпадений нет — возвращается пустой массив [], а не 404.

Параметры URL

Параметр	Обязательный	Описание
username	Да	Имя владельца репозитория (пользователь или организация)
reponame	Да	Название репозитория без расширения .git
ref	Нет	Префикс для поиска ссылок без refs/. Примеры: heads/feature, tags/v2. Если опущен — возвращаются все ссылки репозитория

Параметры запроса

Данный метод не принимает параметров в строке запроса.

Тело запроса

Не требуется.

Пример запроса

# Все ветки с префиксом "feature"
curl -X GET "https://api.gitverse.ru/repos/user/APInewTestRepo/git/matching-refs/heads/feature" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# Все теги версий v2.x
curl -X GET "https://api.gitverse.ru/repos/user/APInewTestRepo/git/matching-refs/tags/v2" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# Все ветки репозитория
curl -X GET "https://api.gitverse.ru/repos/user/APInewTestRepo/git/matching-refs/heads/" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# Все ссылки репозитория (без параметра ref)
curl -X GET "https://api.gitverse.ru/repos/user/APInewTestRepo/git/matching-refs/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ (200 OK)

[
  {
    "ref": "refs/heads/feature/auth",
    "url": "https://api.gitverse.ru/repos/user/APInewTestRepo/git/refs/heads/feature/auth",
    "object": {
      "type": "commit",
      "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
      "url": "https://api.gitverse.ru/repos/user/APInewTestRepo/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
    }
  },
  {
    "ref": "refs/heads/feature/billing",
    "url": "https://api.gitverse.ru/repos/user/APInewTestRepo/git/refs/heads/feature/billing",
    "object": {
      "type": "commit",
      "sha": "bb329f671234567890abcdef1234567890abcdef",
      "url": "https://api.gitverse.ru/repos/user/APInewTestRepo/commits/bb329f671234567890abcdef1234567890abcdef"
    }
  }
]

Если совпадений нет:

[]

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

application/vnd.gitverse.object+json;version=latest

Поля ответа

Поле	Тип	Описание
ref	string	Полное имя ссылки, начиная с refs/
url	string (uri)	URL ссылки в Public API
object.type	string	Тип git-объекта, на который указывает ссылка: commit для веток и обычных тегов; tag для аннотированных тегов
object.sha	string	SHA-хеш git-объекта (40 символов)
object.url	string (uri)	URL коммита: /repos/{username}/{reponame}/commits/{sha}

Коды ответа

Код	Статус	Описание
200	OK	Запрос успешен. Возвращается массив ссылок (возможно пустой)
409	Conflict	Репозиторий пуст или git-репозиторий недоступен
500	Internal Server Error	Внутренняя ошибка при получении ссылок

Примечания

1. Совпадение происходит по началу имени: запрос heads/feat найдет refs/heads/feature/auth, но не refs/heads/hotfix-feat.
2. Параметр ref передается без префикса refs/: пишите heads/feature, не refs/heads/feature.
3. Чтобы получить все ветки — используйте heads/, все теги — tags/, все ссылки репозитория — пропустите параметр ref совсем.
4. Если совпадений нет — возвращается 200 OK с пустым массивом, не 404.