Code Traveler

Introducing GitHubApiStatus

Brandon Minnick -

What is it?

GitHubApiStatus is an open-source library, available on NuGet, to make it easy to understand and leverage the Rate Limits for all of  GitHub's APIs:

  • GitHub's REST API
  • GitHub's Search API
  • GitHub's GraphQL API
  • GitHub's Source Import API
  • GitHub's App Manifest Configuration API

Each GitHub API has different rate limiting rules. For example, you may exceed the rate limit for GitHub's REST API, but that does not mean you've exceeded the rate limit for GitHub's GraphQL API.

Why Does This Exist?

If you've ever had to use the GitHub REST APIs, you may be familiar with GitHub's API Rate Limits:

This means that if you call a GitHub API more than 5,000 times within a 60-minute window, even if you are authenticated, the GitHub APIs will return 403 FORBIDDEN.

But, did you also know that GitHub uses a completely different rate limit for its GraphQL API:

And to make matters EVEN MORE COMPLICATED, GitHub has different rate limit rules arounds its Search APIs, its Code Scanning APIs and its App Manifest Code Conversion APIs.

When creating my open-source GitHub Insights mobile app, GitTrends, I encountered some very frustrating bugs by not understanding the GitHub API Rate Limits.

After learning the ins-and-outs of GitHub API Rate Limits, I wanted to share this expertise with the world.

Hopefully this library helps prevent headaches from future developers using the GitHub APIs!

How Do I Use it?

Initialize GitHubApiStatusService by passing in your GitHub Personal Access Token:

var gitHubApiStatusService = new GitHubApiStatusService(new AuthenticationHeaderValue("bearer", "Your GitHub Personal Access Token, e.g. 123456789012345"));

Then, call Task<GitHubApiRateLimits> GitHubApiStatusService.GetApiRateLimits() to see the current status of the GitHub API Rate Limits:

var apiRateLimits = await gitHubApiStatusService.GetApiRateLimits();

// REST API Results
Console.WriteLine($"What is the GitHub REST API Rate Limit? {apiRateLimits.RestApi.RateLimit}"); // What is the GitHub REST API Rate Limit? 5000
Console.WriteLine($"How many REST API requests do I have remaining? {apiRateLimits.RestApi.RemainingRequestCount}"); // How many REST API requests do I have remaining? 4983
Console.WriteLine($"How long until the GitHub REST API Rate Limit resets? {apiRateLimits.RestApi.RateLimitReset_TimeRemaining}"); // How long until the GitHub REST API Rate Limit resets? 00:40:13.8035515
Console.WriteLine($"When does the GitHub REST API Rate Limit reset? {apiRateLimits.RestApi.RateLimitReset_DateTime}"); // When does the GitHub REST API Rate Limit reset? 10/29/2020 3:28:58 AM +00:00

Console.WriteLine();

// GraphQL API Results
Console.WriteLine($"What is the GitHub GraphQL API Rate Limit? {apiRateLimits.GraphQLApi.RateLimit}"); // What is the GitHub GraphQL API Rate Limit? 5000
Console.WriteLine($"How many GraphQL API requests do I have remaining? {apiRateLimits.GraphQLApi.RemainingRequestCount}"); // How many GraphQL API requests do I have remaining? 5000
Console.WriteLine($"How long until the GitHub GraphQL API Rate Limit resets? {apiRateLimits.GraphQLApi.RateLimitReset_TimeRemaining}"); // How long until the GitHub GraphQL API Rate Limit resets? 00:59:59.8034526
Console.WriteLine($"When does the GitHub GraphQL API Rate Limit reset? {apiRateLimits.GraphQLApi.RateLimitReset_DateTime}"); // When does the GitHub GraphQL API Rate Limit reset? 10/29/2020 3:48:44 AM +00:00

How do I use it with ASP.NET Core?

First, install the GitHubApiStatus.Extensions NuGet Package.

In ConfigureServices, add it to the IServiceCollection using services.AddGitHubApiStatusService(...), passing in your GitHub Personal Access Token:

public class Startup
{
    // ...

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGitHubApiStatusService(new AuthenticationHeaderValue("bearer", "[Your GitHub Personal Access Token, e.g. 123456789012345]"), new ProductHeaderValue("MyApp"))
            .ConfigurePrimaryHttpMessageHandler(config => new HttpClientHandler { AutomaticDecompression = System.Net.DecompressionMethods.GZip | System.Net.DecompressionMethods.Deflate });

        services.AddRazorPages();
    }

    /// ...
    
}

Then reference IGitHubApiStatusService from any constructor:

class MyPageModel : PageModel
{
    readonly ILogger<IndexModel> _logger;
    readonly IGitHubApiStatusService _gitHubApiStatusService;

    public MyPageModel(IGitHubApiStatusService gitHubApiStatusService, ILogger<MyPageModel> logger)
    {
        _logger = logger;
        _gitHubApiStatusService = gitHubApiStatusService;
    }

    // ...
}

How do I use it with Blazor?

(Check out this open-source Blazor sample app)

First, install the GitHubApiStatus.Extensions NuGet Package.

In Program.cs, add it to the IServiceCollection using builder.Services.AddGitHubApiStatusService(...), passing in your GitHub Personal Access Token:

public class Program
{
    public static Task Main(string[] args)
    {
        var builder = WebAssemblyHostBuilder.CreateDefault(args);
        builder.RootComponents.Add<App>("#app");
        builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

        // AddGitHubApiStatusService 
        builder.Services.AddGitHubApiStatusService(new AuthenticationHeaderValue("bearer", "[Your GitHub Personal Access Token, e.g. 123456789012345]"), new ProductHeaderValue("YourAppName"))
            .ConfigurePrimaryHttpMessageHandler(config => new HttpClientHandler { AutomaticDecompression = System.Net.DecompressionMethods.GZip | System.Net.DecompressionMethods.Deflate });

        return builder.Build().RunAsync();
    }
}

Then inject IGitHubApiStatusService into any Blazor page:

@page "/graphql"
@using GitHubApiStatus
@inject IGitHubApiStatusService GitHubApiStatusService

<h1>GitHub REST Api Status</h1>

<p>@_graphQLApiStatus</p>

<button class="btn btn-primary" @onclick="GetGraphQLApiStatus">Get Status</button>

@code {
    string _graphQLApiStatus = string.Empty;

    async Task GetGraphQLApiStatus()
    {
        var apiRateLimitStatuses = await GitHubApiStatusService.GetApiRateLimits(System.Threading.CancellationToken.None).ConfigureAwait(false);
        _graphQLApiStatus = apiRateLimitStatuses.GraphQLApi.ToString();
    }
}

Apps Using GitHubApiStatus

Here are a few open-source apps using GitHubApiStatus:

GitTrends (Xamarin)

GitTrends is an open-source iOS and Android app that provides insights into your GitHub Repos. Quickly and easily review your total Views, Clones and Stars for each and understand the referring sites to your repositories!

GitStatus (Xamarin)

GitStatus is an open-source iOS and Android app that displays your current rate limit for the GitHub REST API and the GitHub GraphQL API.

GitStatus.Blazor (Blazor)

GitStatus.Blazor is an open-source website that displays your current rate limit for the GitHub REST API and the GitHub GraphQL API.