mirror of
https://github.com/hasura/graphql-engine.git
synced 2025-01-07 08:13:18 +03:00
4c1c69b339
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/5118 Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> GitOrigin-RevId: dffacc23b0496fc398a1687ab0bc67bd0fd5156c
132 lines
4.9 KiB
Plaintext
132 lines
4.9 KiB
Plaintext
---
|
|
description: Hasura GraphQL API Explorer
|
|
keywords:
|
|
- hasura
|
|
- cloud
|
|
- docs
|
|
- api
|
|
- explorer
|
|
- public
|
|
- graphQL
|
|
- graphiQL
|
|
sidebar_label: GraphQL API Explorer
|
|
sidebar_position: 240
|
|
sidebar_class_name: cloud-icon
|
|
# adding index slug in case this root doc becomes a directory later
|
|
slug: graphql-api-explorer/index
|
|
---
|
|
|
|
import Thumbnail from '@site/src/components/Thumbnail';
|
|
|
|
# Hasura GraphQL API Explorer
|
|
|
|
## TL;DR
|
|
|
|
Browse, query, mutate, and subscribe to any GraphQL endpoint with our free, full-featured, in-browser
|
|
[GraphiQL app](https://cloud.hasura.io/public/graphiql) without having to log into Hasura.
|
|
|
|
## Introduction
|
|
|
|
The Hasura GraphQL API Explorer is a free and full-featured GraphiQL UI which is able to query, mutate, or subscribe to
|
|
any GraphQL endpoint.
|
|
|
|
You're able to use this feature to share and test an API endpoint with anyone who has the public URL.
|
|
|
|
The API Explorer replaces Hasura's legacy GraphQL API exploration tool, [GraphQL Online](https://graphiql-online.com/).
|
|
|
|
## Try out a public GraphQL API
|
|
|
|
From the [API Explorer landing page](https://cloud.hasura.io/public/graphiql), you can use the quick links on the left
|
|
of the page to try out some existing public GraphQL APIs including **SpaceX**, **GitHub**, or **GraphQL Jobs**.
|
|
|
|
<Thumbnail
|
|
src='/img/graphql/cloud/api-explorer/connect-to-existing-api_graphql-api-explorer_v1.png'
|
|
alt='API Explorer Landing Page'
|
|
width='1146px'
|
|
/>
|
|
|
|
:::info Note
|
|
|
|
For the GitHub GraphQL API you can generate an [API token for yourself here](https://github.com/settings/tokens). Once
|
|
generated, replace the `<enter your token here>` placeholder in the `Authorization` header with your token to gain
|
|
access.
|
|
|
|
:::
|
|
|
|
## Connect to any GraphQL API
|
|
|
|
You can use the Hasura GraphQL API explorer to connect to any publicly available GraphQL endpoint. Add your endpoint URL
|
|
to the endpoint field and click "Connect to Endpoint".
|
|
|
|
<Thumbnail
|
|
src='/img/graphql/cloud/api-explorer/connect-to-api_graphql-api-explorer_v1.png'
|
|
alt='API Explorer Share Link'
|
|
width='1146px'
|
|
/>
|
|
|
|
Once connected you are able to add any headers you may need to provide authentication or other parameters to the
|
|
endpoint.
|
|
|
|
<Thumbnail
|
|
src='/img/graphql/cloud/api-explorer/add-headers_graphql-api-explorer_v1.png'
|
|
alt='API Explorer Share Link'
|
|
width='1146px'
|
|
/>
|
|
|
|
## Testing a Hasura Cloud project
|
|
|
|
Using the GraphQL API Explorer to test a Hasura Cloud project with public access requires only two pieces of
|
|
configuration for the project. Most importantly, you must set up unauthenticated access user roles. You can achieve this
|
|
by creating an `anonymous` role with the respective permissions.
|
|
[Read more here](/auth/authorization/common-roles-auth-examples.mdx#anonymous-users-example) for detailed
|
|
steps.
|
|
|
|
The other piece of configuration is setting the `HASURA_GRAPHQL_UNAUTHORIZED_ROLE` environment variable to `anonymous`.
|
|
[Read more](/auth/authentication/unauthenticated-access.mdx#configuring-unauthenticated--public-access) on
|
|
how to set up unauthenticated/public access user roles.
|
|
|
|
The Hasura Cloud Project GraphQL API is publicly sharable, to allow users to access it without authentication. Navigate
|
|
to the project settings to find the public, sharable URL.
|
|
|
|
<Thumbnail
|
|
src='/img/graphql/cloud/api-explorer/share-link_graphql-api-explorer_v1.png'
|
|
alt='API Explorer Share Link'
|
|
width='1146px'
|
|
/>
|
|
|
|
:::info Note
|
|
|
|
If an [admin secret](/deployment/securing-graphql-endpoint.mdx) is configured for your Hasura project,
|
|
Hasura GraphQL Engine will automatically reject unauthenticated requests. In this case, for the project to be publicly
|
|
accessible, the admin secret has to be passed as a header in the GraphiQL interface under the **Request Headers**
|
|
section. Be careful not to leak a production admin secret publicly.
|
|
|
|
<Thumbnail
|
|
src='/img/graphql/cloud/api-explorer/admin-secret-header_graphql-api-explorer_v1.png'
|
|
alt='API Explorer Header Admin Secret'
|
|
width='1146px'
|
|
/>
|
|
:::
|
|
|
|
### Shareable URL construction
|
|
|
|
Here are the supported, optional, configuration options which can be passed as URL query parameters to create a
|
|
shareable URL to the GraphQL Explorer. These must be [http URL encoded](https://www.urlencoder.org/).
|
|
|
|
| Parameter | Description |
|
|
| --------- | ------------------------------------------------------------------------------------------------------ |
|
|
| endpoint | URL pointing to a GraphQL service. |
|
|
| header | HTTP header to be supplied with requests. Multiple headers can be given by repeating the header param. |
|
|
|
|
Example:
|
|
|
|
```http
|
|
https://cloud.hasura.io/public/graphiql?header=content-type:application/json&header=Authorization:bearer%20%3Center%20your%20token%20here%3E&endpoint=https://api.github.com/graphql
|
|
```
|
|
|
|
:::info Note
|
|
|
|
The header `content-type` is set to `application/json` by default if not provided in the URL.
|
|
|
|
:::
|