REST API, GraphQL API, gh api, Pagination, Rate Limits, and Automation Clients: Concepts, Architecture, and Mental Model

1. The problem: API automation needs more than a successful request

Earlier chapters used gh api to inspect workflows, packages, security findings, environments, and attestations. Those examples were deliberately narrow. A production client has to preserve correctness when the collection spans many pages, when the resource is private, when GitHub returns a throttling response, when GraphQL returns partial data, or when a create request succeeds on the server but the client loses the response.

Start with a durable rule: HTTP success is not the same as complete business truth. A first-page 200 OK can still omit most repositories. A GraphQL 200 can include an errors array. A timed-out POST can still have created the object. The client must model the hosted resource, authorization boundary, traversal contract, and desired state before it mutates anything.

2. Mental model: identity → contract → traversal → decision → mutation

              flowchart TD
                I["Automation identity"] --> A["Authentication"]
                A --> Z["Authorization"]
                Z --> R["REST resource + version"]
                Z --> G["GraphQL schema + query"]
                R --> P["Link/page traversal"]
                G --> C["Connection/cursor traversal"]
                P --> E["Complete normalized evidence"]
                C --> E
                E --> D["Policy / dry-run decision"]
                D --> N{"Mutation needed?"}
                N -->|no| O["No-op evidence"]
                N -->|yes| M["Duplicate/idempotence guard"]
                M --> W["Bounded write"]
                W --> V["Read-after-write verification"]
                R -. status/rate headers .-> B["Backoff controller"]
                G -. errors/rateLimit .-> B
            

Authentication answers “who is calling?” Authorization answers “what may that identity do to this owner/resource?” REST and GraphQL then expose two different contracts over GitHub objects. Pagination is part of correctness, not a performance afterthought. Only a complete, error-checked input set should reach a mutation decision.

3. REST resources versus GraphQL schema

REST is often clearer for one resource or collection. GraphQL can reduce calls when a client needs related fields across several objects, but query depth, node counts, cost, and partial-error handling become part of the design.

4. Authentication, API versions, media types, and ownership

Current GitHub REST integrations should send Accept: application/vnd.github+json and an explicit supported X-GitHub-Api-Version. The course baseline is 2026-03-10. GitHub currently documents that a REST request without the version header falls back to 2022-11-28; do not make that implicit fallback part of a production contract.

gh api   -H "Accept: application/vnd.github+json"   -H "X-GitHub-Api-Version: 2026-03-10"   repos/OWNER/REPO --jq '{full_name,visibility,default_branch}' 

gh api uses the authenticated GitHub CLI identity. If you intentionally want to observe public unauthenticated behavior, use a client that omits Authorization, such as curl; do not manipulate or expose the CLI credential store.

5. Pagination is a correctness requirement

Many REST list endpoints return a subset. GitHub documents a default of 30 items for many endpoints and a maximum per_page of 100 for most endpoints, but each endpoint reference is authoritative. Follow the server-provided Link header until rel="next" disappears.

gh api --paginate   -H "X-GitHub-Api-Version: 2026-03-10"   "repos/OWNER/REPO/issues?state=all&per_page=2"   --jq '.[] | {number,title,state}' 

GraphQL connections require first or last from 1 through 100. Request pageInfo { hasNextPage endCursor } and feed the previous cursor into after. gh api graphql --paginate expects an $endCursor: String variable and the relevant pageInfo fields.

6. Primary and secondary rate limits

On GitHub.com, current primary limits include 60 REST requests per hour for unauthenticated public-data requests and generally 5,000 REST requests per hour for an authenticated user. GraphQL generally provides 5,000 points per hour for a user. Rate budget is not authorization.

Secondary rate limits protect service reliability even when primary budget remains. Current guidance discusses concurrency, endpoint/query point pressure, CPU time, and mutation bursts. A REST throttling response can be 403 or 429; GraphQL may surface rate errors with HTTP 200 or 403. Honor Retry-After; if x-ratelimit-remaining reaches zero, wait until x-ratelimit-reset; otherwise back off exponentially and stop after a bounded number of attempts.

gh api -i -H "X-GitHub-Api-Version: 2026-03-10" rate_limit --silent

gh api graphql -f query='query { viewer { login } rateLimit { cost remaining resetAt } }' 

7. Conditional requests, retries, and idempotence

Many REST responses include ETag, and many include Last-Modified. An authenticated conditional GET that returns 304 Not Modified does not count against the primary REST rate limit. This is useful for low-frequency reconciliation when an event is unavailable.

8. Read-only inspection before mutation

gh --version
gh auth status
gh api -i -H "X-GitHub-Api-Version: 2026-03-10" user --jq '{login,id}'
gh api -i -H "X-GitHub-Api-Version: 2026-03-10" rate_limit --silent
gh api graphql -f query='query { viewer { login } rateLimit { cost remaining resetAt } }' 

Production logs should capture safe request evidence such as operation/endpoint, host, status, GitHub request ID, duration, page/item counts, and rate metadata. Never log bearer tokens, Authorization headers, whole private response bodies, or sensitive fields the client does not need.

9. Why this matters in DevOps

API clients become control-plane software: they inventory repositories, create issues/deployments, manage policy, and connect GitHub to other systems. A first-page bug can omit half an estate; a blind POST retry can duplicate incidents; an over-scoped identity can turn one parsing flaw into a broad compromise. Treat API automation like production software: explicit contracts, least privilege, complete traversal, bounded resource use, observable decisions, and verified state transitions.

Knowledge check

Summary

Correct GitHub API automation treats REST/GraphQL as permissioned, versioned, paginated, rate-limited contracts. The client names its host/identity/resource, retrieves every page, inspects errors/status/rate metadata, minimizes fields, uses conditional reads or events where appropriate, makes dry-run/desired-state decisions, and verifies the hosted result.

Official references

• REST API versions
• REST pagination
• REST rate limits
• REST best practices
• REST troubleshooting
• REST authentication
• GraphQL pagination
• GraphQL rate/query limits
• GitHub CLI gh api