jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 09:57:42 -05:00
Code Issues Projects Releases Wiki Activity

[GraphQL] Updating docs with GraphQL Explorer retirement (#57163)

Browse Source 
Co-authored-by: Johanan <johanan@forcepush.tech>
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
This commit is contained in:
Alena Sviridenko
2025-08-22 16:37:43 +02:00
committed by GitHub
parent f933494c97
commit 35eb0002bd
8 changed files with 89 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/graphql/guides/forming-calls-with-graphql.md
View File

@@ -49,7 +49,7 @@ If you access {% data variables.product.github %} at a different domain, such as
## Communicating with GraphQL
Because GraphQL operations consist of multiline JSON, GitHub recommends using the [Explorer](/graphql/guides/using-the-explorer) to make GraphQL calls. You can also use `curl` or any other HTTP-speaking library.
Because GraphQL operations consist of multiline JSON, GitHub recommends using the [GraphQL Clients](/graphql/guides/using-graphql-clients) to make GraphQL calls. You can also use `curl` or any other HTTP-speaking library.
In REST, [HTTP verbs](/rest#http-verbs) determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is `POST`. The exception is an [introspection query](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), which is a simple `GET` to the endpoint. For more information on GraphQL versus REST, see [AUTOTITLE](/graphql/guides/migrating-from-rest-to-graphql).

2
content/graphql/guides/index.md
View File

@@ -14,7 +14,7 @@ children:
- /forming-calls-with-graphql
- /using-global-node-ids
- /migrating-from-rest-to-graphql
- /using-the-explorer
- /using-graphql-clients
- /using-pagination-in-the-graphql-api
- /managing-enterprise-accounts
- /using-the-graphql-api-for-discussions

7
content/graphql/guides/managing-enterprise-accounts.md
View File

@@ -39,10 +39,7 @@ For a list of the fields available with the Enterprise Accounts API, see [AUTOTI
## Getting started using GraphQL for enterprise accounts
Follow these steps to get started using GraphQL to manage your enterprise accounts:
* Authenticating with a {% data variables.product.pat_generic %}
* Choosing a GraphQL client or using the GraphQL Explorer
* Setting up Insomnia to use the GraphQL API
See [AUTOTITLE](/graphql/guides/using-graphql-clients) to get started using GraphQL to manage your enterprise accounts.
For some example queries, see [An example query using the Enterprise Accounts API](#an-example-query-using-the-enterprise-accounts-api).
@@ -206,5 +203,5 @@ For more information about getting started with GraphQL, see [AUTOTITLE](/graphq
For more details about the new queries, mutations, and schema defined types available for use with the Enterprise Accounts API, see the sidebar with detailed GraphQL definitions from any [GraphQL reference page](/graphql).
You can access the reference docs from within the GraphQL explorer on GitHub. For more information, see [AUTOTITLE](/graphql/guides/using-the-explorer#accessing-the-sidebar-docs).
You can access the reference docs from within the GraphQL clients. For more information, see [AUTOTITLE](/graphql/guides/using-graphql-clients).
For other information, such as authentication and rate limit details, check out the [guides](/graphql/guides).

74
content/graphql/guides/using-graphql-clients.md Normal file
View File

@@ -0,0 +1,74 @@
---
title: Using GraphQL Clients
intro: 'You can run queries on real {% data variables.product.prodname_dotcom %} data using various GraphQL clients and libraries.'
redirect_from:
- /v4/guides/using-the-explorer
- /graphql/guides/using-the-explorer
versions:
fpt: '*'
ghec: '*'
ghes: '*'
topics:
- API
---
## Using GraphQL client IDEs
There are many open-source GraphQL client IDEs you can use to access {% data variables.product.company_short %}'s GraphQL API.
See [AUTOTITLE](/graphql/guides/forming-calls-with-graphql) for extensive information on HTTP methods, authentication, and GraphQL call structure.
First, choose a client. Common options include GraphiQL, Insomnia, and Altair (desktop/web/extension). You can see the full list of clients in the [GraphQL organization's tool directory](https://graphql.org/community/tools-and-libraries/?tags=services).
The following generic instructions will work with most GraphQL clients:
1. Point the client at the GraphQL endpoint: `{% data variables.product.graphql_url %}`.
1. Add an `Authorization` header: `Authorization: Bearer TOKEN` (replace `TOKEN` with your {% data variables.product.company_short %} {% data variables.product.pat_generic %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)).
1. Set the request method to `POST` or if it's available, use the client-provided GraphQL mode.
1. Enter your query or mutation in the editor and, if needed, provide variables in the "Variables" panel.
Example:
```graphql
query {
viewer {
login
}
}
```
1. If your client needs a schema for documentation rendering or autocomplete, fetch it via a GraphQL introspection query. Many clients can do this automatically from the "Docs" panel.
Minimal introspection query:
```graphql
query IntrospectionQuery {
__schema {
types {
name
}
}
}
```
1. Run the request and inspect the JSON response. Query from example should return the login associated with the {% data variables.product.company_short %} {% data variables.product.pat_generic %} you authenticated with.
Use the client UI to explore docs, run queries, and save requests as needed.
## {% data variables.product.prodname_cli %}
You can also use the command line with {% data variables.product.prodname_cli %} to run GraphQL queries.
1. Install and [authenticate with {% data variables.product.prodname_cli %}](https://cli.github.com/manual/gh_auth_login).
1. Run a query against `{% data variables.product.graphql_url %}` using the GraphQL endpoint with the [`gh api` subcommand](https://cli.github.com/manual/gh_api).
Example:
```shell
gh api graphql -f query='query { viewer { login } }'
```
This should return the login associated with the {% data variables.product.company_short %} {% data variables.product.pat_generic %} you authenticated with.
## Requesting support
{% data reusables.support.help_resources %}

152
content/graphql/guides/using-the-explorer.md
View File

@@ -1,152 +0,0 @@
---
title: Using the Explorer
intro: 'You can run queries on real {% data variables.product.prodname_dotcom %} data using the GraphQL Explorer, an integrated development environment in your browser that includes docs, syntax highlighting, and validation errors.'
redirect_from:
- /v4/guides/using-the-explorer
versions:
fpt: '*'
ghec: '*'
ghes: '*'
topics:
- API
---
## About the GraphQL Explorer
{% ifversion ghec %}
> [!NOTE]
> If your {% data variables.product.prodname_ghe_cloud %} organization uses {% data variables.product.prodname_dotcom %}'s IP allow list, you won't be able to use the GraphQL Explorer. Instead, we recommend using an alternative GraphQL client IDE.
{% endif %}
{% ifversion fpt or ghec %}
[GraphQL Explorer](/graphql/overview/explorer) is an instance of [GraphiQL](https://github.com/graphql/graphiql), which is a "graphical interactive in-browser GraphQL IDE."
{% else %}
[GraphiQL](https://github.com/graphql/graphiql), also referred to in this documentation as the GraphQL Explorer, is a "graphical interactive in-browser GraphQL IDE."
{% endif %}
## Query autocompletion
You can use query autocompletion to help you build queries. In the main pane, within the curly brackets of your query, use <kbd>control</kbd>+<kbd>space</kbd> or <kbd>shift</kbd>+<kbd>space</kbd> to display the autocomplete menu.
## Accessing the sidebar docs
All types in a GraphQL schema include a `description` field compiled into documentation. The collapsible **Docs** pane on the right side of the Explorer page allows you to browse documentation about the type system. The docs are automatically updated and will drop fields that are {% data variables.release-phases.closing_down %}.
> [!NOTE]
> The **Docs** sidebar contains the same content that is automatically generated from the schema under [AUTOTITLE](/graphql), though it is formatted differently in places.
## Using the variable pane
Some example calls include [variables](/graphql/guides/forming-calls-with-graphql#working-with-variables) written like this:
```graphql
query($number_of_repos:Int!){
viewer {
name
repositories(last: $number_of_repos) {
nodes {
name
}
}
}
}
variables {
"number_of_repos": 3
}
```
This is the correct format to submit the call using a `POST` request in a `curl` command (as long as you [escape newlines](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql)).
If you want to run the call in the Explorer, enter the `query` segment in the main pane and the variables in the **Query Variables** pane below it. Omit the word `variables` from the Explorer:
```graphql
{
"number_of_repos": 3
}
```
## Using the Altair GraphQL Client IDE
There are many open source GraphQL client IDEs. For example, you can use Altair to access {% data variables.product.company_short %}'s GraphQL API. To access the GraphQL API with Altair, download and install it from [altair-graphql/altair](https://github.com/altair-graphql/altair). Then, follow the configuration steps below.
### Configuring Altair
1. Get an [access token](/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql).
1. Launch Altair.
1. In the left sidebar, below the Altair logo, click **Set Headers**. A new window will open.
1. In the "Header key" field, enter `Authorization`.
1. In the "Header value" field, enter `Bearer TOKEN`, replacing `TOKEN` with your token from the first step.
1. Click **Save** in the bottom right corner of the window to save your authorization header.
1. In the "GraphQL Endpoint" field, enter your GraphQL URL, such as `{% data variables.product.graphql_url %}`.
1. To load the {% data variables.product.company_short %} GraphQL schema, download the [public schema](/graphql/overview/public-schema).
1. In Altair, click on **Docs** on the top right, then the three dots and **Load Schema...**
1. Select the file public schema that you downloaded in an earlier step.
> [!NOTE]
> For more information about why `POST` is the method, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql).
You can test your access by querying yourself:
```graphql
query {
viewer {
login
}
}
```
If everything worked correctly, this will display your login. You're all set to start making queries.
## Requesting support
{% data reusables.support.help_resources %}
## Troubleshooting errors
Because GraphQL is [introspective](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), the Explorer supports:
* Intelligent typeaheads aware of the current schema
* Validation error previews as you type
If you enter a query that is not well-formed or does not pass [schema validation](/graphql/guides/introduction-to-graphql#schema), a popup warns you of an error. If you run the query, the error returns in the response pane.
A GraphQL response contains several keys: a `data` hash and an `errors` array.
```json
{
"data": null,
"errors": [
{
"message": "Objects must have selections (field 'nodes' returns Repository but has no selections)",
"locations": [
{
"line": 5,
"column": 8
}
]
}
]
}
```
It's possible you might run into an unexpected error that is not related to the schema. If this happens, the message will include a reference code you can use when reporting the issue:
```json
{
"data": null,
"errors": [
{
"message": "Something went wrong while executing your query. This is most likely a GitHub bug. Please include \"7571:3FF6:552G94B:69F45B7:5913BBEQ\" when reporting this issue."
}
]
}
```
> [!NOTE]
> {% data variables.product.prodname_dotcom %} recommends checking for errors before using data in a production environment. In GraphQL, failure is not total: portions of GraphQL queries may succeed while others fail.

2
content/graphql/index.md
View File

@@ -8,7 +8,7 @@ featuredLinks:
startHere:
- /graphql/guides/forming-calls-with-graphql
- /graphql/guides/introduction-to-graphql
- /graphql/guides/using-the-explorer
- /graphql/guides/using-graphql-clients
popular:
- /graphql/overview/explorer
- /graphql/overview/public-schema

10
content/graphql/overview/explorer.md
View File

@@ -13,7 +13,15 @@ topics:
autogenerated: graphql
---
For more information about how to use the explorer, see [AUTOTITLE](/graphql/guides/using-the-explorer).
<!-- expires 2025-11-01 -->
<!-- We should change this to a note describing what's happened once the date is reached. -->
> [!WARNING]
> The GraphQL Explorer as an embedded tool will be removed from the documentation on November 1, 2025. See our [changelog announcement](https://github.blog/changelog/2025-08-22-graphql-explorer-removal-from-api-documentation-on-november-1-2025).
For more information about how to explore {% data variables.product.prodname_dotcom %} GraphQL Schema, see [AUTOTITLE](/graphql/guides/using-graphql-clients).
<!-- end expires 2025-11-01 -->
{% ifversion ghec %}

2
content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md
View File

@@ -13,7 +13,7 @@ shortTitle: Sponsors GraphQL API
To get started with the GraphQL API, see [AUTOTITLE](/graphql/guides/introduction-to-graphql).
You can find the details about the Sponsors GraphQL API in the reference docs. For more information, see [AUTOTITLE](/graphql/reference). We recommend using the GraphQL explorer to build your GraphQL calls. For more information, see [AUTOTITLE](/graphql/guides/using-the-explorer).
You can find the details about the Sponsors GraphQL API in the reference docs. For more information, see [AUTOTITLE](/graphql/reference). We recommend using the GraphQL clients to build your GraphQL calls. For more information, see [AUTOTITLE](/graphql/guides/using-graphql-clients).
## Known Issues