REST API 入门

在路径前面附加 GitHub REST API 的基 URL https://api.github.com，以获取完整 URL：https://api.github.com/octocat。

在命令行中使用 curl 命令。 使用 --request 或 -X 标志，后跟 HTTP 方法。 使用 --url 标志，后跟完整 URL。

curl --request GET \
--url "https://api.github.com/octocat"

在 curl 命令中，会发送包含令牌的 Authorization 标头。 将 YOUR-TOKEN 替换为你的令牌：

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

还可以在 GitHub Actions 工作流中使用 run 关键字执行 curl 命令。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

GitHub 建议使用内置 GITHUB_TOKEN 进行身份验证，而不是创建令牌。 如果无法执行此操作，请将令牌存储为机密，并将以下示例中的 GITHUB_TOKEN 替换为机密的名称。 有关 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。 有关机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/octocat" \
          --header "Authorization: Bearer $GH_TOKEN"

若要在 curl 命令中发送标头，请使用 --header 或 -H 标志，后跟采用 key: value 格式的标头。

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

若要从 octocat/Spoon-Knife 存储库获取问题，请将 {owner}替换为 octocat，并将 {repo} 替换为 Spoon-Knife。 若要生成完整路径，请在前面附加 GitHub REST API 的基 URL https://api.github.com：https://api.github.com/repos/octocat/Spoon-Knife/issues。

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

对于 curl 命令，向路径末尾添加 ?，然后采用 parameter_name=value 形式追加查询参数名称和值。 使用 & 分隔多个查询参数。

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2&sort=updated&direction=asc" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

某些操作使用属于数组的查询参数。 要在查询字符串中发送数组，请为每个数组项使用查询参数一次，并在查询参数名称后追加 []。 例如，要提供两个存储库 ID 的数组，请使用 ?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID。

对于 curl，使用 --data 标志在 JSON 对象中传递正文参数。

curl --request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

若要查看状态代码和标头，请在发送请求时使用 --include 或 --i 标志。

例如，以下请求：

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

返回响应代码和标头，如下所示：

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

在此示例中，响应代码为 200，指示请求成功。

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

例如，可使用 > 将响应重定向到文件：

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

然后可以使用 jq 获取每个问题的标题和创建者 ID：

jq '.[] | {title: .title, authorID: .user.id}' data.json

前面两个命令返回类似于下面这样的内容：

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

有关 jq 的详细信息，请参阅 jq 文档。