diff --git a/content/graphql/guides/forming-calls-with-graphql.md b/content/graphql/guides/forming-calls-with-graphql.md index 223cbeb2b1..21b786568e 100644 --- a/content/graphql/guides/forming-calls-with-graphql.md +++ b/content/graphql/guides/forming-calls-with-graphql.md @@ -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). diff --git a/content/graphql/guides/index.md b/content/graphql/guides/index.md index f27999c590..91f5b3d88a 100644 --- a/content/graphql/guides/index.md +++ b/content/graphql/guides/index.md @@ -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 diff --git a/content/graphql/guides/managing-enterprise-accounts.md b/content/graphql/guides/managing-enterprise-accounts.md index 2a99fc1a60..4b00abbb3e 100644 --- a/content/graphql/guides/managing-enterprise-accounts.md +++ b/content/graphql/guides/managing-enterprise-accounts.md @@ -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). diff --git a/content/graphql/guides/using-graphql-clients.md b/content/graphql/guides/using-graphql-clients.md new file mode 100644 index 0000000000..8cb9ddcad3 --- /dev/null +++ b/content/graphql/guides/using-graphql-clients.md @@ -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 %} diff --git a/content/graphql/guides/using-the-explorer.md b/content/graphql/guides/using-the-explorer.md deleted file mode 100644 index 80b1ce9f69..0000000000 --- a/content/graphql/guides/using-the-explorer.md +++ /dev/null @@ -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 control+space or shift+space 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. diff --git a/content/graphql/index.md b/content/graphql/index.md index 10d5e0b38b..d7f6bef63e 100644 --- a/content/graphql/index.md +++ b/content/graphql/index.md @@ -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 diff --git a/content/graphql/overview/explorer.md b/content/graphql/overview/explorer.md index 48ae0f44dc..c1795a6ef9 100644 --- a/content/graphql/overview/explorer.md +++ b/content/graphql/overview/explorer.md @@ -13,7 +13,15 @@ topics: autogenerated: graphql --- -For more information about how to use the explorer, see [AUTOTITLE](/graphql/guides/using-the-explorer). + + + +> [!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). + + {% ifversion ghec %} diff --git a/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md b/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md index 7a68421d97..10c7cb39df 100644 --- a/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md +++ b/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md @@ -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