GitHub API Breaking Changes: REST vs GraphQL Migration Guide

Published: May 2026 • 10 min read

GitHub maintains two APIs: the REST API (v3) and the GraphQL API (v4). Both evolve continuously, and GitHub regularly deprecates endpoints and fields. If your application integrates with GitHub — whether for CI/CD automation, code review tools, or repository management — staying ahead of breaking changes is critical to avoid unexpected failures.

REST API vs GraphQL: What's Changing

GitHub has been steadily shifting investment toward the GraphQL API. While the REST API remains fully supported, several patterns indicate where the platform is headed:

• New features land in GraphQL first — GitHub's newer functionality (Projects V2, Discussions, Copilot metrics) is GraphQL-only
• REST endpoints get deprecated regularly — GitHub marks REST endpoints as deprecated via headers and sunset dates
• GraphQL schema evolves continuously — Fields get deprecated with @deprecated directives rather than version bumps
• REST uses media type versioning — The Accept: application/vnd.github+json header controls response format

How GitHub REST API Versioning Works

GitHub's REST API uses a date-based media type for versioning. You specify the API version via the Accept header:

Accept: application/vnd.github+json
Accept: application/vnd.github.v3+json
Accept: application/vnd.github.cloak-preview+json

Key versioning behaviors:

• Without a specific media type, you get the current default version
• Preview features require specific media types (e.g., symmetra-preview for security advisories)
• Deprecated endpoints return Sunset and Deprecation headers
• GitHub announces deprecations in their changelog with migration timelines

Common GitHub REST API Breaking Changes

Endpoint Removals

GitHub periodically removes endpoints that have been deprecated. Recent examples include:

• Legacy search endpoints replaced by newer equivalents
• Team permission endpoints restructured for organization-level access
• Git database endpoints changing response formats
• Integration/webhook endpoints migrating to GitHub App model

Response Field Changes

Fields get added, removed, or restructured:

• permissions objects expanding from simple booleans to detailed role objects
• User objects gaining new fields like plan changes
• Repository objects restructuring visibility and forking fields
• Pull request review objects changing thread structure

Authentication Changes

GitHub has made significant authentication changes:

• Personal access tokens now require fine-grained scopes
• OAuth token format changes (prefix requirements)
• GitHub App installation tokens replacing PATs for automation
• SSH key authentication requirements tightening

GraphQL API Deprecation Patterns

The GraphQL API handles deprecation differently. Instead of removing fields, GitHub marks them as deprecated:

query {
  repository(owner: "octocat", name: "Hello-World") {
    # This field may be deprecated
    watchers {
      totalCount
    }
    # New replacement field
    stargazerCount
  }
}

GraphQL deprecation signals:

• Fields marked with @deprecated(reason: "...") in the schema
• Introspection queries reveal deprecated fields and their replacements
• GitHub's changelog announces GraphQL deprecations with migration paths
• Deprecated fields eventually return errors instead of data

Monitoring GitHub API Changes

Manual Monitoring

You can track GitHub API changes by:

• Reading the GitHub API changelog
• Watching the github/rest-api-description repo for OpenAPI spec updates
• Monitoring Sunset headers in API responses
• Running GraphQL introspection queries to detect deprecated fields

Automated Monitoring

SchemaWatch monitors GitHub's OpenAPI spec automatically. The GitHub REST API spec is published as a machine-readable OpenAPI document, making automated diff detection straightforward.

SchemaWatch detects:

• New endpoints added to the API
• Endpoints marked as deprecated or removed
• Request/response schema field additions and removals
• Enum value changes (new status values, type changes)
• Authentication requirement changes

You receive alerts with exact diffs, so you know immediately when a change affects your integration.

Migration Strategy: REST to GraphQL

If you're considering migrating from REST to GraphQL, follow this approach:

1. Audit your REST usage — Identify which endpoints you call and what data you need
2. Check GraphQL coverage — Verify that the GraphQL API provides the same data (most REST resources have GraphQL equivalents)
3. Migrate incrementally — Replace one REST call at a time, not the entire integration at once
4. Handle rate limits differently — GraphQL uses a node-based rate limit system, not request counting
5. Test with the GraphQL explorer — Use GitHub's built-in GraphQL Explorer to prototype queries
6. Monitor both APIs — Until fully migrated, monitor both REST and GraphQL specs for changes

Best Practices for GitHub API Integration

1. Use the latest stable media type — Don't rely on the default; explicitly set your API version header
2. Handle Sunset headers — Parse Sunset headers to detect deprecations before they become breaking
3. Implement graceful degradation — Your code should handle missing fields or new error responses
4. Log API responses — Track response structures so you can detect when they change
5. Subscribe to the changelog — GitHub's API changelog is the primary source for upcoming changes
6. Automate spec monitoring — Manual tracking doesn't scale; use tooling to watch for schema changes

Conclusion

GitHub's APIs evolve rapidly. Whether you use REST, GraphQL, or both, proactive monitoring of API changes prevents production incidents. The combination of reading the changelog and automated schema monitoring gives you the best coverage against unexpected breaking changes.