通过 curl 掌握 GitHub API：实用教程 – wiki大全

作者： /

通过 curl 掌握 GitHub API：实用教程

GitHub API 是开发者生态系统中的强大工具，允许我们以编程方式与 GitHub 平台进行交互。无论是自动化工作流、构建集成服务还是简单地获取仓库信息，GitHub API 都提供了丰富的端点和灵活的访问方式。而 curl，这个命令行工具中的瑞士军刀，则是探索和使用这些 API 的绝佳伙伴。

本教程将详细介绍如何使用 curl 来与 GitHub API 进行交互，涵盖认证、常见请求类型以及实用示例。

前言：什么是 curl 和 GitHub API？

  • curl: 一个命令行工具，用于通过各种协议（包括 HTTP、HTTPS）传输数据。它功能强大，支持各种认证方法、请求头、请求体等，是测试和与 RESTful API 交互的首选工具。
  • GitHub API: 一套基于 REST 的接口，允许开发者以编程方式访问和操作 GitHub 上的数据。它提供了大量端点，用于管理用户、仓库、问题、拉取请求、Gist 等资源。

准备工作

在开始之前，请确保你满足以下条件：

  1. 安装 curl: 大多数 Linux/macOS 系统都预装了 curl。Windows 用户可以通过 Git Bash 或在 PowerShell 中安装 curl (如 winget install curl)。
  2. GitHub 账号: 你需要一个 GitHub 账号来生成个人访问令牌并进行 API 调用。
  3. 了解 JSON: GitHub API 的请求和响应主体通常使用 JSON 格式。

GitHub API 认证

为了与 GitHub API 进行更高级的交互（例如创建仓库、更新 Gist），你需要进行认证。最常用的认证方式是使用个人访问令牌（Personal Access Token, PAT）。

1. 创建个人访问令牌 (PAT)

  1. 登录 GitHub。
  2. 点击右上角的个人资料图片，然后选择 Settings。
  3. 在左侧导航栏中，点击 Developer settings。
  4. 点击 Personal access tokens，然后选择 Tokens (classic)。
  5. 点击 Generate new token。
  6. 给你的令牌一个有意义的名称（例如 “curl-api-test”）。
  7. 选择令牌的权限范围 (Scopes)。这是非常重要的一步，你应根据需要授予最小权限。例如，如果你想读取仓库信息，只需选择 repo:public_repo 或 repo。如果想创建 Gist，则选择 gist。
  8. 点击 Generate token。
  9. 复制生成的令牌！ 这将是你最后一次看到它。请妥善保管，它和密码一样重要。

2. 使用 PAT 进行认证

在 curl 请求中，通过 Authorization 请求头传递你的 PAT：

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

将 YOUR_PERSONAL_ACCESS_TOKEN 替换为你刚刚生成的 PAT。

基本 curl 请求类型与 GitHub API 示例

GitHub API 主要遵循 RESTful 架构，因此我们会用到常见的 HTTP 方法：GET、POST、PATCH 和 DELETE。

1. GET 请求：获取数据

GET 请求用于从 API 获取资源。

获取当前认证用户的信息

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

  • -H: 用于设置 HTTP 请求头。这里我们设置了 Authorization 头，包含了我们的 PAT。

预期响应（部分）:

json
{
"login": "your_username",
"id": 1234567,
"node_id": "MDQ6VXNlcjEyMzQ1Njc=",
"avatar_url": "https://avatars.githubusercontent.com/u/1234567?v=4",
"name": "Your Name",
// ... 其他信息
}

获取特定用户的所有公共仓库

bash
curl https://api.github.com/users/octocat/repos

这里我们不需要认证，因为请求的是公共数据。

获取特定仓库的信息

bash
curl https://api.github.com/repos/octocat/Spoon-Knife

2. POST 请求：创建资源

POST 请求用于在 API 上创建新的资源。

创建一个公共 Gist

首先，确保你的 PAT 拥有 gist 权限。

bash
curl -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
-X POST \
-d '{
"description": "A simple curl test gist",
"public": true,
"files": {
"hello_world.txt": {
"content": "Hello GitHub API from curl!"
},
"test.md": {
"content": "This is a markdown file.\n\n- Item 1\n- Item 2"
}
}
}' \
https://api.github.com/gists

  • -H "Accept: application/vnd.github.v3+json": 建议设置此头，指定你期望的 API 版本和数据格式。
  • -X POST: 指定请求方法为 POST。
  • -d: 用于发送请求体数据。这里我们发送了一个 JSON 字符串，描述了要创建的 Gist。

预期响应（部分）:

json
{
"url": "https://api.github.com/gists/a1b2c3d4e5f6...",
"forks_url": "https://api.github.com/gists/a1b2c3d4e5f6.../forks",
"commits_url": "https://api.github.com/gists/a1b2c3d4e5f6.../commits",
"id": "a1b2c3d4e5f6...",
"node_id": "G_kwDOAB_iVNoADa...",
"git_pull_url": "https://gist.github.com/a1b2c3d4e5f6....git",
"git_push_url": "https://gist.github.com/a1b2c3d4e5f6....git",
"html_url": "https://gist.github.com/a1b2c3d4e5f6...",
"public": true,
"description": "A simple curl test gist",
"comments": 0,
"user": null,
// ... 其他信息
}
记下响应中的 id 字段，后续更新和删除操作会用到。

3. PATCH 请求：更新资源

PATCH 请求用于部分更新现有资源。

更新之前创建的 Gist 的描述和文件内容

假设你之前创建的 Gist ID 是 a1b2c3d4e5f6。

bash
curl -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
-X PATCH \
-d '{
"description": "Updated description for my curl test gist",
"files": {
"hello_world.txt": {
"content": "Hello again, GitHub API!"
},
"new_file.js": {
"content": "console.log('This is a new file!');"
},
"test.md": null
}
}' \
https://api.github.com/gists/a1b2c3d4e5f6

  • "test.md": null: 通过将文件内容设置为 null 来删除该文件。

4. DELETE 请求：删除资源

DELETE 请求用于删除指定资源。

删除之前创建的 Gist

bash
curl -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" \
-X DELETE \
https://api.github.com/gists/a1b2c3d4e5f6

如果成功，GitHub API 会返回一个 204 No Content 状态码，表示请求已成功处理，但没有返回内容。

常见 GitHub API 端点（概述）

  • 用户:
    • GET /user: 获取认证用户的信息。
    • GET /users/:username: 获取特定用户的信息。
    • GET /user/emails: 获取认证用户的邮箱（需要 user:email 权限）。
  • 仓库:
    • GET /user/repos: 获取认证用户的所有仓库。
    • GET /users/:username/repos: 获取特定用户的所有公共仓库。
    • GET /orgs/:org/repos: 获取组织的所有仓库。
    • GET /repos/:owner/:repo: 获取特定仓库的详细信息。
    • POST /user/repos: 为认证用户创建一个新仓库（需要 public_repo 或 repo 权限）。
  • 问题 (Issues):
    • GET /repos/:owner/:repo/issues: 获取仓库的所有问题。
    • POST /repos/:owner/:repo/issues: 在仓库中创建新问题。
  • 拉取请求 (Pull Requests):
    • GET /repos/:owner/:repo/pulls: 获取仓库的所有拉取请求。
  • Gists:
    • GET /gists: 获取认证用户的所有 Gist。
    • GET /gists/public: 获取所有公共 Gist。
    • POST /gists: 创建一个 Gist。
    • DELETE /gists/:gist_id: 删除一个 Gist。

这只是冰山一角，GitHub API 文档（developer.github.com/v3/）包含了所有可用的端点及其详细说明。

实用技巧

  • JSON 解析: curl 返回的 JSON 响应可能很长。使用 jq 工具可以方便地解析和格式化 JSON：
    bash
    curl -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" https://api.github.com/user | jq '.'
    或者只提取特定字段：
    bash
    curl -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" https://api.github.com/user | jq '.login'
  • 速率限制: GitHub API 对每小时的请求数量有限制。你可以通过响应头 X-RateLimit-Limit (限制总数) 和 X-RateLimit-Remaining (剩余数量) 来查看：
    bash
    curl -i https://api.github.com/users/octocat
    -i 会显示响应头信息。
  • 分页: 对于返回大量数据的端点，GitHub API 会进行分页。响应头中的 Link 字段会提供下一页、上一页等链接。

结论

通过 curl 与 GitHub API 交互是理解和调试 API 的基本且有效的方式。它让你能够直接看到 HTTP 请求和响应的细节，这对于学习 API 结构和排除故障非常有帮助。掌握了 curl，你就掌握了与任何 RESTful API 交互的强大能力。现在，去探索 GitHub API 的无限可能吧！

滚动至顶部