“gh api” is a command provided by GitHub CLI (Command-Line Interface) that allows users to make authenticated HTTP requests to the GitHub API and retrieve the corresponding responses. GitHub API is a set of endpoints that enables developers to interact with various GitHub functionalities programmatically.
With “gh api,” users can perform a wide range of operations on GitHub repositories, issues, pull requests, users, and more, directly from the command-line interface. This command simplifies the process of making API requests and retrieving data without the need for manual API authentication or handling of API tokens.
Here are the key features and functionalities of “gh api”:
- Authenticated Requests: “gh api” supports making authenticated requests to the GitHub API. It automatically handles the authentication process, allowing users to access and interact with resources that require authentication, such as private repositories or user-specific data.
- HTTP Request Methods: Users can specify different HTTP request methods, including GET, POST, PUT, PATCH, DELETE, and others, to perform various operations on GitHub resources. This flexibility allows users to create, update, delete, or retrieve information as needed.
- Endpoint URL and Parameters: Users can specify the endpoint URL for the desired GitHub API resource and provide additional parameters to customize the request. This allows users to target specific resources, filter results, or pass necessary data for the operation.
- Response Printing: “gh api” retrieves the response from the GitHub API and prints it directly to the command-line interface. This allows users to quickly see the response data, including the requested information or any error messages or status codes returned by the API.
- Pagination and Filtering: The command supports pagination and filtering options provided by the GitHub API. Users can retrieve paginated results or apply filters to narrow down the response based on specific criteria.
By using “gh api,” developers and users can automate tasks, integrate GitHub functionalities into their workflows, and access GitHub data programmatically. It provides a convenient way to interact with the GitHub API without leaving the command-line environment.
gh api Command Examples
1. Display the subcommand help:
# gh api --help
2. Display the releases for the current repository in JSON format:
# gh api repos/:owner/:repo/releases
3. Create a reaction for a specific issue:
# gh api --header Accept:application/vnd.github.squirrel-girl-preview+json --raw-field 'content=+1' repos/:owner/:repo/issues/123/reactions
4. Display the result of a GraphQL query in JSON format:
# gh api graphql --field name=':repo' --raw-field 'query'
5. Send a request using a custom HTTP method:
# gh api --method POST endpoint
6. Include the HTTP response headers in the output:
# gh api --include endpoint
7. Do not print the response body:
# gh api --silent endpoint
8. Send a request to a specific GitHub Enterprise Server:
# gh api --hostname github.example.com endpoint
Summary
Overall, “gh api” enhances the capabilities of GitHub CLI by offering a command-line interface to make authenticated HTTP requests to the GitHub API. It simplifies the process of working with GitHub resources, retrieving data, and performing operations programmatically, making it a valuable tool for developers and users who want to interact with GitHub from the command line.