🎉 Версия 16.0.0. Что новенького? →
База знаний
Публичное API
Работа с файлами

Работа с файлами в репозитории
Beta

Описание

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

Общие замечания

  1. Для версий API указывайте заголовок Accept с соответствующей версией:
Accept: application/vnd.gitverse+json;version=1
  1. Для работы с приватными ресурсами требуется авторизация через Bearer токен:
Authorization: Bearer \{user_token}
  1. Базовый URL для всех конечных точек:
https://api.gitverse.ru
  1. Если запрос завершается неудачно, API возвращает объект ошибки с кодом состояния HTTP и сообщением.
  2. Все даты возвращаются в формате ISO 8601.

Описание метода: создание файла

PUT /repos/{username}/{reponame}/contents/{filename}

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

  • {username} — имя владельца репозитория;
  • {reponame} — название репозитория;
  • {filename} — путь к файлу, который будет создан (например, README.md, src/main.go).

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

  • Content-Type: application/json: указывает, что тело запроса будет в формате JSON;
  • Accept: application/vnd.gitverse+json;version=1: указывает версию API. В данном случае используется версия 1;
  • Authorization: Bearer \{user_token}: токен авторизации пользователя, который создает файл.

Тело запроса

Тело запроса должно содержать JSON-объект с параметрами нового файла:

  • branch (string, опционально): имя существующей ветки, в которую будет добавлен файл. Если не указано, используется ветка по умолчанию (обычно main или master);
  • content (string, обязательно): содержимое файла, закодированное в Base64;
  • new_branch (string, опционально): имя новой ветки, которая будет создана для этого изменения. Если указано, изменение будет выполнено в новой ветке;
  • signoff (boolean, опционально): добавлять ли подпись (Signed-off-by) в коммит. По умолчанию false.

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

{
	"branch": "main",
	"content": "dGVzdCBjb250ZW50IG9mIGZpbGUK",
	"new_branch": "feature/new-file",
	"signoff": true
}

Ответ сервера

Ответ содержит информацию о созданном файле и связанном коммите.

Пример успешного ответа

{
	"content": {
		"name": "README.md",
		"path": "README.md",
		"sha": "eaf894a5ebd8e5a75aa2eecac4965ea86d2d571e",
		"size": 20,
		"url": "https://api.gitverse.ru/repos/example_user/russia/contents/README.md",
		"html_url": "https://gitverse.ru/example_user/russia/blob/main/README.md",
		"git_url": "https://api.gitverse.ru/repos/example_user/russia/git/blobs/eaf894a5ebd8e5a75aa2eecac4965ea86d2d571e",
		"download_url": "https://gitverse.ru/example_user/russia/raw/main/README.md",
		"type": "file"
	},
	"commit": {
		"sha": "cc33bd2dd8f0812eafd7e4fd64998139169c6b05",
		"node_id": "MDY6Q29tbWl0MTIzNDU2Nzg5OA==",
		"url": "https://api.gitverse.ru/repos/example_user/russia/git/commits/cc33bd2dd8f0812eafd7e4fd64998139169c6b05",
		"html_url": "https://gitverse.ru/example_user/russia/commit/cc33bd2dd8f0812eafd7e4fd64998139169c6b05",
		"author": {
			"name": "example_user",
			"email": "qwe@mail.com",
			"date": "2025-04-14T16:37:35+03:00"
		},
		"committer": {
			"name": "example_user",
			"email": "qwe@mail.com",
			"date": "2025-04-14T16:37:35+03:00"
		},
		"message": "Add README.md",
		"tree": {
			"sha": "eaf894a5ebd8e5a75aa2eecac4965ea86d2d571e",
			"url": "https://api.gitverse.ru/repos/example_user/russia/git/trees/eaf894a5ebd8e5a75aa2eecac4965ea86d2d571e"
		},
		"parents": [
			{
				"sha": "abc123def456ghi789jkl012mno345pqr678stu901",
				"url": "https://api.gitverse.ru/repos/example_user/russia/git/commits/abc123def456ghi789jkl012mno345pqr678stu901",
				"html_url": "https://gitverse.ru/example_user/russia/commit/abc123def456ghi789jkl012mno345pqr678stu901"
			}
		]
	}
}

Описание метода: изменение файла

PUT /repos/{username}/{reponame}/contents/{filename}

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

  • {username} — имя владельца репозитория;
  • {reponame} — название репозитория;
  • {filename} — путь к файлу, который будет изменён.

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

  • Content-Type: application/json: указывает, что тело запроса будет в формате JSON;
  • Accept: application/vnd.gitverse+json;version=1: указывает версию API. В данном случае используется версия 1;
  • Authorization: Bearer \{user_token}: токен авторизации пользователя, который изменяет файл.

Тело запроса

Тело запроса должно содержать JSON-объект с параметрами изменения файла:

  • branch (string, опционально): имя существующей ветки, в которой находится файл. Если не указано, используется ветка по умолчанию (обычно main или master);
  • content (string, обязательно): новое содержимое файла, закодированное в Base64;
  • sha (string, обязательно): SHA хеш текущего содержимого файла. Требуется для проверки, что файл не был изменён другим пользователем;
  • from_path (string, опционально): если файл переименовывается, указывает старый путь к файлу;
  • message (string, опционально): сообщение коммита;
  • new_branch (string, опционально): имя новой ветки, которая будет создана для этого изменения. Если указано, изменение будет выполнено в новой ветке;
  • signoff (boolean, опционально): добавлять ли подпись (Signed-off-by) в коммит. По умолчанию false.

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

{
	"branch": "main",
	"content": "dGVzdCBjb250ZW50IG9mIGZpbGUgbWV0aG9kIHB1dA==",
	"sha": "5f643138ec9b86561094ff1f6e5a7bad310a431a",
	"from_path": "",
	"message": "new msg 123",
	"new_branch": "",
	"signoff": true
}

Ответ сервера

Ответ содержит информацию об изменённом файле и связанном коммите. Структура ответа аналогична ответу при создании файла.

Обработка ошибок

Если запрос завершается неудачно, API возвращает объект ошибки с кодом состояния HTTP и сообщением.

Пример ошибки

{
	"error": "Unauthorized",
	"message": "Authentication is required to access this resource.",
	"status": 401
}

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

  • 400 Bad Request: неверные параметры запроса (например, отсутствуют обязательные поля);
  • 401 Unauthorized: необходима авторизация;
  • 403 Forbidden: у пользователя нет прав на выполнение действия;
  • 404 Not Found: репозиторий или файл не найдены;
  • 409 Conflict: файл уже существует в указанной ветке или SHA хеш не совпадает;
  • 500 Internal Server Error: внутренняя ошибка сервера.

Дополнительная информация

  1. Для создания или изменения файла требуется авторизация через токен.
  2. Если параметр branch не указан, используется ветка по умолчанию (обычно main или master).
  3. Если параметр new_branch указан, изменение будет выполнено в новой ветке.
  4. Содержимое файла должно быть закодировано в Base64.
  5. Если файл уже существует в указанной ветке, запрос завершится ошибкой 409 Conflict, если не указан корректный SHA хеш.

Если у вас возникнут вопросы или потребуется дополнительная информация, пожалуйста, обратитесь к документации API или свяжитесь с поддержкой.

Получение файла/директорииУдаление файлов