GitHub API Essential Guide

What type of API does GitHub provide?

GitHub offers multiple types of APIs, including both REST and GraphQL:

REST API

GitHub provides a comprehensive REST API that allows developers to interact with various GitHub resources and perform actions programmatically. Some key points about GitHub's REST API include:

• It follows REST principles and uses standard HTTP methods like GET, POST, PUT, PATCH, DELETE
• Responses are returned in JSON format
• It provides access to most GitHub features like repositories, issues, pull requests, users, etc.
• Authentication is done via OAuth tokens or personal access tokens

GraphQL API

In addition to REST, GitHub also offers a GraphQL API. Some important aspects of GitHub's GraphQL API are:

• It provides more flexibility in querying and retrieving exactly the data needed
• Allows combining multiple API calls into a single request
• Strongly typed schema that provides better error handling
• Used for more complex queries and data retrieval scenarios

Key Considerations

• The REST API is more widely used and easier to get started with for basic operations
• The GraphQL API offers more power and flexibility for complex use cases
• GitHub recommends using GraphQL for production applications when possible
• Both APIs can be used together as needed depending on the specific requirements

In summary, GitHub provides both REST and GraphQL APIs to cater to different developer needs and use cases. The REST API offers simplicity while GraphQL provides more advanced querying capabilities. Developers can choose the appropriate API based on their specific requirements.

Does the GitHub API have webhooks?

Yes, the GitHub API has webhooks. Webhooks allow you to subscribe to specific events on GitHub and receive notifications when they occur. Key points about GitHub webhooks include:

Webhook Availability

• Available for repositories, organizations, GitHub Marketplace accounts, GitHub Sponsors accounts, and GitHub Apps
• Can be created using the GitHub web interface or REST API

Event Types

• Repository events: push, pull_request, create, delete
• Organization events: member, team
• Sponsorship events: sponsorship
• Marketplace events
• Meta events: meta

Key Considerations

• Payload size limit: 25 MB
• Event selection: All events or specific events
• Payload URL: Required for webhook delivery
• Secret key: For security and validation
• Content type: JSON or form-encoded payloads

Best Practices

• Subscribe only to necessary events
• Use a secret key for validation
• Monitor payload size
• Implement proper error handling and logging

GitHub webhooks are useful for integrating external systems with GitHub and automating workflows based on GitHub events.

Rate Limits and other limitations

Here are the key points about the API rate limits for the GitHub API:

Primary Rate Limits

• Unauthenticated requests: 60 requests per hour

• Authenticated requests with personal access token: 5,000 requests per hour

• GitHub Apps owned by GitHub Enterprise Cloud organizations: 15,000 requests per hour

• OAuth apps owned/approved by GitHub Enterprise Cloud organizations: 15,000 requests per hour (for members of that org)

• GitHub Actions (using GITHUB_TOKEN):

  • 1,000 requests per hour per repository
  • 15,000 requests per hour per repository for GitHub Enterprise Cloud

• GitHub App installations:

  • Minimum 5,000 requests per hour
  • 15,000 requests per hour for GitHub Enterprise Cloud organizations
  • Can scale up to 12,500 requests per hour based on number of users/repos

Secondary Rate Limits

GitHub also enforces secondary rate limits to prevent abuse, including:

• Max 100 concurrent requests
• Max 900 points per minute for REST API endpoints
• Max 2,000 points per minute for GraphQL API
• Max 90 seconds of CPU time per 60 seconds of real time
• Limits on content creation requests

Key Points

• Rate limits are applied per user/token, not per application

• Different endpoints may have different specific rate limits

• Rate limit information is returned in API response headers

• GraphQL API has a separate rate limit from the REST API

• Using GraphQL can help spread out rate limit usage in some cases

• Authenticated requests have much higher limits than unauthenticated

• Enterprise accounts get higher limits in many cases

Best Practices

• Authenticate requests whenever possible to get higher limits

• Consider using GitHub Apps instead of personal access tokens for higher and scalable limits

• Use GraphQL API when appropriate to leverage separate rate limit pool

• Monitor rate limit headers and adjust request rate as needed

By understanding and working within these rate limits, developers can optimize their use of the GitHub API while avoiding throttling issues.

Latest API Version

Based on the search results, here are the key points about the most recent version of the GitHub API:

1. The most recent version of the GitHub REST API is 2022-11-28, released on November 28, 2022.

2. To specify an API version when making requests, you should use the X-GitHub-Api-Version header. For example:

   curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen
   

3. Requests without the X-GitHub-Api-Version header will default to using the 2022-11-28 version.

4. GitHub uses date-based versioning for their API. The version name is based on the date when the API version was released.

5. When a new REST API version is released, the previous API version will be supported for at least 24 more months following the release of the new API version.

6. Breaking changes are introduced in new API versions, while additive (non-breaking) changes are available in all supported API versions.

7. Before upgrading to a new API version, it's recommended to read the changelog of breaking changes and test your integration with the new version.

To ensure you're using the most up-to-date version of the GitHub API, you should include the X-GitHub-Api-Version:2022-11-28 header in your API requests. It's also a good practice to periodically check the GitHub API documentation for any updates or new versions.

How to get a GitHub developer account and API Keys?

To get a developer account for GitHub to create an API integration, you can follow these steps:

Join the GitHub Developer Program

1. The GitHub Developer Program is open to individual developers and companies who meet certain criteria:

   • You have an integration in production or development that uses the GitHub API
   • You have an email address where GitHub users can contact you for support

2. You don't need a paid GitHub account to join the program anymore (this requirement was removed in 2019).

Requirements for joining

To join the GitHub Developer Program, you need to have:

• An integration that uses the GitHub API (either in production or development)
• An email address for user support
• Optionally, a website for your integration (you can use GitHub Pages if you don't have one)

Benefits of joining

By joining the GitHub Developer Program, you'll get access to:

• Early notifications about API changes
• Ability to try new features before they launch
• Developer licenses to build and test your application against GitHub Enterprise
• Opportunity to submit your work for consideration on the integrations page

How to register

1. Go to the GitHub Developer Program page (https://developer.github.com/program/).

2. Click on the "Join the GitHub Developer Program" button.

3. Fill out the required information, including:

   • Your GitHub username
   • The name of your integration
   • A brief description of your integration
   • The URL of your integration (or GitHub repository)
   • Your support email address

4. Review and accept the terms of service.

5. Submit your application.

Next steps

Once you've joined the GitHub Developer Program, you can start using the GitHub API to build your integration:

1. Choose an endpoint for your API requests from the GitHub REST API documentation.
2. Identify the HTTP method and path for the endpoint you want to use.
3. Replace any required path parameters with your specific values.
4. Make API requests using tools like GitHub CLI, curl, or JavaScript.

Remember to follow best practices when creating your GitHub App, such as using webhooks efficiently and implementing proper authentication methods.

What can you do with the GitHub API?

Based on the GitHub API documentation, here are the main data models you can interact with using the GitHub API, along with key points about what is possible for each:

Repositories

• Create, update, delete, and manage repositories
• Get repository contents, commits, branches, and tags
• Manage repository collaborators and teams
• Create and manage forks
• Configure repository settings and webhooks
• Interact with repository issues, pull requests, and projects
• Manage repository releases and assets

Users and Organizations

• Get user and organization profile information
• Manage organization members and teams
• Update user and organization settings
• Get user activity like starred repositories and followers

Issues and Pull Requests

• Create, update, and close issues and pull requests
• Add labels, assignees, and milestones
• Manage comments on issues and pull requests
• Review and merge pull requests
• Get issue and PR timelines and events

Projects

• Create and manage project boards
• Add, move, and update project cards and columns
• Link issues and pull requests to project cards

Actions and Workflows

• Manage and trigger workflow runs
• Get workflow run logs and artifacts
• Manage self-hosted runners
• Configure repository and organization secrets

Git Data

• Create and update Git refs, tags, and trees
• Get commit data and file contents
• Create and update blobs

Checks

• Create check runs and check suites
• Update check run status and output
• Get check run and check suite details

Apps and OAuth

• Manage GitHub App installations and permissions
• Create and revoke OAuth tokens
• Get rate limit and API usage information

Search

• Search repositories, code, issues, users, etc.
• Filter and sort search results

Webhooks

• Create and manage repository and organization webhooks
• Receive webhook payloads for various GitHub events

This covers the major data models, but the GitHub API provides access to many other resources as well. The API allows you to programmatically interact with most aspects of GitHub's functionality.