GitHub REST API v3 提供了一套完整的、公开的 JSON 接口供开发者使用。本文详细介绍常见的 GitHub API v3 端点，包括仓库管理、用户资料、搜索功能、组织管理等，并通过实际代码示例展示如何使用这些无需认证即可调用的公开接口。

GitHub REST API v3 常用端点完全指南

引言

GitHub 本身就是通过一套正式的 REST API (v3) 提供了你提到的 /repos/.../releases 这种 JSON 接口供开发者使用。这些接口不是”隐藏的”，而是公开的、可调用的，只是大多数人不知道完整的路径。你可以直接用 curl 去访问它们（返回 JSON）——很多都不需要额外文档或者登录就能获取公共数据。

API 基础信息：

• 根端点: https://api.github.com
• 数据格式: JSON
• 认证方式: 公开接口无需认证，私有接口使用 Personal Access Token (PAT)
• 官方文档: https://docs.github.com/en/rest
• API 版本: REST API v3 (当前版本 2022-11-28)

重要提醒：”隐藏 API”、”未记录 API” 在 GitHub 这种成熟平台上一般不鼓励使用，因为这类接口可能随时改变或者失效（甚至可能违反使用条款）。本文只介绍官方公开的 REST API endpoints，这些端点稳定可靠，有完整文档支持。

---

📌 仓库相关（Repository）

这些接口与你提到的 releases 类似，结构都是：

获取仓库信息

curl https://api.github.com/repos/owner/repo

返回字段：name, description, language, stargazers_count, forks_count, open_issues_count, created_at, updated_at, homepage 等

获取 Tags（标签）

curl https://api.github.com/repos/owner/repo/tags

示例：获取 mflux 项目的所有 tags

curl https://api.github.com/repos/filipstrand/mflux/tags | jq '.[:5] | {name, commit: .commit.sha, message}'

获取分支列表

curl https://api.github.com/repos/owner/repo/branches

获取 Issue 列表

# 获取所有 issues（包含 open 和 closed）
curl https://api.github.com/repos/owner/repo/issues

# 只获取 open issues
curl https://api.github.com/repos/owner/repo/issues?state=open

# 获取 closed issues
curl https://api.github.com/repos/owner/repo/issues?state=closed

# 使用 per_page 控制每页返回数量
curl "https://api.github.com/repos/owner/repo/issues?per_page=100"

获取 Pull Requests

# 获取所有 PRs
curl https://api.github.com/repos/owner/repo/pulls

# 只获取 open PRs
curl https://api.github.com/repos/owner/repo/pulls?state=open

# 只获取 merged PRs
curl https://api.github.com/repos/owner/repo/pulls?state=merged

获取 Contributors（贡献者）

curl https://api.github.com/repos/owner/repo/contributors

获取 Repository Contents（文件/目录）

# 获取根目录文件列表
curl https://api.github.com/repos/owner/repo/contents/

# 获取子目录
curl https://api.github.com/repos/owner/repo/contents/src

# 读取单个文件
curl https://api.github.com/repos/owner/repo/contents/README.md

# 获取原始内容（需要 base64 解码）
curl https://api.github.com/repos/owner/repo/contents/README.md?ref=main | jq -r '.content' | base64 -d

---

👤 用户相关

获取用户基本资料

curl https://api.github.com/users/USERNAME

返回字段：login, id, avatar_url, gravatar_id, type, site_admin, public_repos, followers, following, created_at 等

获取认证用户资料（需要 Token）

curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/user

用户粉丝列表

curl https://api.github.com/users/USERNAME/followers

用户关注的人

curl https://api.github.com/users/USERNAME/following

获取用户的公钥

curl https://api.github.com/users/USERNAME/keys

---

🧑‍🤝 组织与团队

组织信息

curl https://api.github.com/orgs/ORGNAME

组织成员列表

curl https://api.github.com/orgs/ORGNAME/members

组织仓库列表

curl https://api.github.com/orgs/ORGNAME/repos

---

🛠 Issues / Pull Requests / Reviews

这些接口用于工作流自动化或代码分析：

Issue 详细信息

curl https://api.github.com/repos/owner/repo/issues/ISSUE_NUMBER

获取 Issue 评论

# 获取所有评论
curl https://api.github.com/repos/owner/repo/issues/ISSUE_NUMBER/comments

# 获取单个评论
curl https://api.github.com/repos/owner/repo/issues/comments/COMMENT_ID

Pull Request 操作

# 获取单个 Pull Request
curl https://api.github.com/repos/owner/repo/pulls/PULL_NUMBER

# 获取 PR 的文件变更
curl https://api.github.com/repos/owner/repo/pulls/PULL_NUMBER/files

# 获取 PR 的状态检查
curl https://api.github.com/repos/owner/repo/pulls/PULL_NUMBER/checks

合并 Pull Request（需要 Token）

curl -X PUT \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/owner/repo/pulls/PULL_NUMBER/merge \
  -d '{"commit_title": "Merge pull request", "commit_message": "Merged"}'

---

🔎 搜索与活动（Events）

搜索代码

curl "https://api.github.com/search/code?q=filename:package.json+language:javascript"

搜索仓库

# 搜索特定仓库
curl "https://api.github.com/search/repositories?q=topic:python+stars:>100"

# 按语言筛选
curl "https://api.github.com/search/repositories?q=language:go"

# 搜索名称包含关键字
curl "https://api.github.com/search/repositories?q=react+in:name"

搜索 Issue

curl "https://api.github.com/search/issues?q=label:bug+state:open+language:python+repo:owner/repo"

搜索用户

curl "https://api.github.com/search/users?q=tom+repos:>10+followers:>100"

Events（公共活动 Feed）

# 获取最新公开事件流
curl https://api.github.com/events

# 获取特定组织的公共事件
curl https://api.github.com/orgs/ORGNAME/events

# 获取特定用户的公共事件
curl https://api.github.com/users/USERNAME/events/public

用途：可用于监控动态，构建活动分析仪表板等。

---

📦 Releases / Assets 进阶（你已经提到的）

除了 /releases 获取完整的发布列表，还有：

获取最新发布

curl https://api.github.com/repos/owner/repo/releases/latest

获取 Tag 信息

# 与 releases 不同，这个返回所有 git tags，包括未关联 release 的 tags
curl https://api.github.com/repos/owner/repo/git/refs/tags

创建版本发布（需要 Token）

curl -X POST \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/owner/repo/releases \
  -d '{
    "tag_name": "v1.0.0",
    "target_commitish": "main",
    "name": "Release 1.0.0",
    "body": "Release notes here",
    "draft": false,
    "prerelease": false
  }'

获取 Release 资产

# 列出所有 release assets
curl https://api.github.com/repos/owner/repo/releases/tags/v1.0.0/assets

# 获取特定资产的元数据
curl https://api.github.com/repos/owner/repo/releases/assets/ASSET_ID

# 直接下载 Release Asset（带 Accept 头返回二进制下载）
curl -L -o filename.zip \
  -H "Accept: application/octet-stream" \
  https://api.github.com/repos/owner/repo/releases/assets/ASSET_ID

---

📊 仓库统计与元数据

获取仓库语言统计

curl https://api.github.com/repos/owner/repo/languages

返回格式：{"Python": 12345, "JavaScript": 6789, ...}

获取社区资料（Community Profile）

curl https://api.github.com/repos/owner/repo/community/profile

返回字段：health_percentage, description, updated_at, license, files 等社区相关信息。

获取统计流量（Traffic）

```bash
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/owner/repo/traffic/clones

curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/owner/repo/traffic/views

---

⚙️ Meta & Rate Limit

Rate limit 状态

# 匿名请求限制
curl -I https://api.github.com/repos/filipstrand/mflux | grep -i "x-ratelimit"

# 认证请求限制
curl -I -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/user | grep -i "x-ratelimit"

限制说明：

• 匿名请求: 每小时 60 次请求
• 认证请求: 每小时 5000 次请求（基于 token）

API 版本信息

curl https://api.github.com/versions

返回示例：["2022-11-28"] - 返回当前支持的 API 版本列表。

Meta 信息

curl https://api.github.com/meta

返回 GitHub 服务的各种元数据信息。

---

📋 实用示例与技巧

1. 使用 jq 处理 JSON 响应

# 提取特定字段
curl https://api.github.com/repos/owner/repo | jq '.name, .description, .stargazers_count'

# 格式化输出
curl https://api.github.com/repos/owner/repo | jq '{name, stars: .stargazers_count, forks: .forks_count, language: .language}'

# 筛选和排序
curl https://api.github.com/repos/owner/repo/issues | jq '[.[] | select(.state == "open")] | sort_by(.created_at) | reverse'

2. 分页处理

# 使用 per_page 参数控制每页返回数量
curl "https://api.github.com/repos/owner/repo/issues?per_page=100&page=1"

# 获取所有 issues（递归获取）
curl "https://api.github.com/repos/owner/repo/issues?per_page=100"

GitHub API 使用 Link header 提供分页链接。

3. 错误处理

# 检查 HTTP 状态码
response=$(curl -w "%{http_code}" -s https://api.github.com/repos/owner/repo)

if [ $response -eq 404 ]; then
  echo "Repository not found"
elif [ $response -eq 403 ]; then
  echo "Forbidden - check permissions"
fi

4. 使用环境变量管理 Token

# 在 .bashrc 或 .zshrc 中设置
echo 'export GITHUB_TOKEN=your_token_here' >> ~/.bashrc
source ~/.bashrc

# 使用环境变量（安全）
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user/repos

5. 组合多个接口获取综合信息

# 获取仓库信息 + 最新 release + 语言统计
owner="owner"
repo="repo"

repo_info=$(curl -s https://api.github.com/repos/$owner/$repo)
latest_release=$(curl -s https://api.github.com/repos/$owner/$repo/releases/latest)
languages=$(curl -s https://api.github.com/repos/$owner/$repo/languages)

echo "Repository: $(echo $repo_info | jq -r '.name')"
echo "Latest Release: $(echo $latest_release | jq -r '.name')"
echo "Languages: $(echo $languages | jq -r 'keys | join(", ")')"

---

🚫 官方 vs 非官方 API

官方公开 API

本文介绍的所有端点都是官方公开的 REST API endpoints，特点：

✅ 稳定可靠：有完整文档支持，不会轻易改变
✅ 无需猜测：端点路径明确，有版本控制
✅ 合规使用：符合 GitHub 使用条款，不会被封禁
✅ 功能完整：覆盖几乎所有 GitHub 功能

官方资源：

• GitHub REST API 文档: https://docs.github.com/en/rest
• GitHub API 认证: https://docs.github.com/en/authentication

非官方 API

❌ “隐藏 API”、”未记录 API”：

• 不稳定：这些接口可能随时改变或失效
• 无文档：没有官方支持，只能猜测和测试
• 风险高：使用可能违反 GitHub 使用条款，账号可能被封禁
• 维护难：接口失效后无法及时获知

风险提示：

• 如果你在浏览器开发者工具中看到的 API 路径不在官方文档中，那很可能是内部接口
• 这类接口包括：调试请求中的内部调用、特殊功能的私有端点等
• 不建议在生产环境或自动化脚本中使用这类接口

---

💡 组合应用示例

你可以组合这些 API Endpoint 来实现很多自动化抓取或者监控功能：

1. 获取仓库最新 Tags / Releases

# 获取所有 releases
curl https://api.github.com/repos/owner/repo/releases | jq '.[] | {name, tag_name, published_at, html_url}'

# 获取最新 release
curl https://api.github.com/repos/owner/repo/releases/latest | jq '{name, tag_name, published_at, body}'

2. 获取 Issues / PRs 列表

# 获取所有 open issues 并按创建时间排序
curl https://api.github.com/repos/owner/repo/issues?state=open \
  | jq '[.[] | sort_by(.created_at) | reverse] | .[] | {number, title, created_at, user: .user.login}'

# 获取最近 merged 的 PRs
curl https://api.github.com/repos/owner/repo/pulls?state=merged \
  | jq '[.[] | sort_by(.merged_at) | reverse] | .[] | {number, title, merged_at}'

3. 获取用户粉丝/关注信息

# 获取粉丝列表
curl https://api.github.com/users/USERNAME/followers | jq '.[] | .login'

# 获取关注的人
curl https://api.github.com/users/USERNAME/following | jq '.[] | .login'

# 统计粉丝数
curl https://api.github.com/users/USERNAME/followers | jq 'length'

4. 搜索仓库或代码内容

# 搜索 Python 项目，stars > 1000
curl "https://api.github.com/search/repositories?q=language:python+stars:>1000" \
  | jq '.items | .[] | {name, html_url, description, stargazers_count}'

# 搜索代码中的特定函数
curl "https://api.github.com/search/code?q=import+numpy+language:python+in:file"

5. 获取 Events Feed 监控动态

# 监控最新的公开事件
curl https://api.github.com/events | jq '.[:10] | .[] | {type, repo: .repo.name, actor: .actor.login, created_at}'

# 监控特定组织的活动
curl https://api.github.com/orgs/ORGNAME/events | jq '.[:10] | .[] | {type, repo: .repo.name, actor: .actor.login, payload}'

---

📚 官方资源

文档

• GitHub REST API 文档: https://docs.github.com/en/rest
• GitHub API 认证指南: https://docs.github.com/en/authentication
• API 版本信息: https://docs.github.com/en/rest/about-the-rest-api/api-versions
• Breaking changes: https://docs.github.com/en/rest/about-the-rest-api/breaking-changes

参考

• Octokit routes index: https://octokit.github.io/routes/cache/api.github.com/v3/index.html
• OpenAPI description: https://docs.github.com/en/rest/about-the-rest-api/about-the-openapi-description-for-the-rest-api

工具库

• Octokit (GitHub 官方工具库): https://github.com/octokit/octokit.js
• GitHub CLI (gh): https://cli.github.com/
• GitHub API Postman Collection: https://github.com/github/rest-api-description

---

🎯 最佳实践

1. 认证管理

# 使用环境变量（安全）
export GITHUB_TOKEN=your_token_here

# 在 shell 配置文件中设置
echo 'export GITHUB_TOKEN=your_token_here' >> ~/.bashrc
source ~/.bashrc

2. 速率限制处理

# 检查 rate limit 状态
curl -I https://api.github.com/repos/filipstrand/mflux | grep -i "x-ratelimit-remaining"

# 响应格式：x-ratelimit-remaining: 58

3. 错误处理

# 检查 HTTP 状态码并处理
response=$(curl -w "%{http_code}" -s https://api.github.com/repos/owner/repo)

if [ $response -eq 404 ]; then
  echo "Repository not found"
elif [ $response -eq 403 ]; then
  echo "Forbidden - check permissions"
elif [ $response -eq 200 ]; then
  echo "Success"
fi

4. 使用 User-Agent

# 设置 User-Agent（推荐）
curl -H "User-Agent: MyApp/1.0" \
  https://api.github.com/user

GitHub 要求设置 User-Agent，否则可能返回 403 错误。

---

🚀 小结

GitHub REST API v3 提供了丰富且稳定的端点来管理仓库、跟踪问题、处理 Pull Request、发布版本、管理用户和组织等。这些公开的、可调用的 JSON 接口让开发者能够：

1. 自动化工作流程: 自动化重复性任务，如备份、监控、通知
2. 集成 GitHub: 将 GitHub 集成到现有工具和系统
3. 构建工具: 创建自定义仪表板、分析工具、监控脚本
4. 管理资源: 编程方式管理代码仓库和团队协作
5. 数据抓取: 获取公开数据进行统计分析

核心要点：

• ✅ 使用官方公开 API，避免使用未记录的接口
• ✅ 它们基本都遵循统一的结构：https://api.github.com/{resource_path}
• ✅ 返回标准 JSON，适合用 curl、脚本或者程序调用
• ✅ 公开接口无需认证，私有接口使用 Personal Access Token
• ✅ 完整的官方文档支持，稳定可靠

通过理解和使用这些端点，你可以大大提高开发效率，将 GitHub 的强大功能发挥到极致。

---

本文基于 GitHub REST API v3 官方文档编写，涵盖了最常用的公开 API 端点和使用场景。