REST与GraphQL-API

1. GitHub API 概述

1.1 两种 API

2. 认证

2.1 Token 类型

2.2 创建 Token

1. Settings → Developer settings → Personal access tokens
2. 选择权限范围
3. 生成并保存 Token

2.3 使用 Token

# REST API
curl -H "Authorization: token ghp_xxxxx" \
  https://api.github.com/user

# GraphQL API
curl -H "Authorization: bearer ghp_xxxxx" \
  -X POST -d '{"query": "{ viewer { login } }"}' \
  https://api.github.com/graphql

# 使用 gh CLI
gh api user

3. REST API

3.1 常用端点

3.2 示例

# 列出仓库
curl -H "Authorization: token ghp_xxxxx" \
  "https://api.github.com/user/repos?per_page=10&sort=updated"

# 创建 Issue
curl -X POST \
  -H "Authorization: token ghp_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bug report","body":"Description","labels":["bug"]}' \
  https://api.github.com/repos/user/repo/issues

# 使用 gh CLI（推荐）
gh api repos/user/repo/issues \
  -f title="Bug report" \
  -f body="Description"

4. GraphQL API

4.1 基本查询

query {
  viewer {
    login
    repositories(first: 10, orderBy: { field: UPDATED_AT, direction: DESC }) {
      nodes {
        name
        description
        stargazerCount
      }
    }
  }
}

4.2 变更操作

mutation {
  createIssue(input: { repositoryId: "REPO_ID", title: "Bug report", body: "Description" }) {
    issue {
      number
      url
    }
  }
}

4.3 使用 gh CLI

gh api graphql -f query='
  query {
    viewer {
      login
      repositories(first: 5) {
        nodes { name }
      }
    }
  }
'

5. 速率限制

5.1 限制规则

5.2 检查剩余配额

# REST API
curl -I https://api.github.com/user
# X-RateLimit-Limit: 5000
# X-RateLimit-Remaining: 4999
# X-RateLimit-Reset: 1718342400

# GraphQL
gh api graphql -f query='{ rateLimit { remaining resetAt } }'

5.3 避免触发限制

• 使用条件请求（ETag / If-Modified-Since）
• 缓存 API 响应
• 使用 GraphQL 减少请求次数
• 使用 Webhooks 替代轮询

6. Webhooks vs API 轮询