diff --git a/docs.json b/docs.json index 01276d469..d956ca380 100644 --- a/docs.json +++ b/docs.json @@ -1157,7 +1157,13 @@ "group": "Consuming APIs", "pages": [ "nightly/portal/developer-app", - "nightly/tyk-stack/tyk-developer-portal/enterprise-developer-portal/api-access/approve-requests" + "nightly/tyk-stack/tyk-developer-portal/enterprise-developer-portal/api-access/approve-requests", + { + "group": "Guides", + "pages": [ + "nightly/tyk-developer-portal/graphql-playground" + ] + } ] }, { diff --git a/img/graphql-api-star-wars-schema.png b/img/graphql-api-star-wars-schema.png new file mode 100644 index 000000000..0d3844ce5 Binary files /dev/null and b/img/graphql-api-star-wars-schema.png differ diff --git a/img/graphql-docs-live-portal.png b/img/graphql-docs-live-portal.png new file mode 100644 index 000000000..8c7e27e15 Binary files /dev/null and b/img/graphql-docs-live-portal.png differ diff --git a/img/graphql-docs-tab-playground-setup.png b/img/graphql-docs-tab-playground-setup.png new file mode 100644 index 000000000..f9ae74047 Binary files /dev/null and b/img/graphql-docs-tab-playground-setup.png differ diff --git a/img/graphql-playground-portal.png b/img/graphql-playground-portal.png new file mode 100644 index 000000000..dca37f398 Binary files /dev/null and b/img/graphql-playground-portal.png differ diff --git a/nightly/api-management/event-driven-apis.mdx b/nightly/api-management/event-driven-apis.mdx index 3a7362533..709445520 100644 --- a/nightly/api-management/event-driven-apis.mdx +++ b/nightly/api-management/event-driven-apis.mdx @@ -105,7 +105,7 @@ The following sections will guide you through the prerequisites and steps to con - **Docker**: We will run the entire Tyk Stack on Docker. For installation, refer to this [guide](https://docs.docker.com/desktop/setup/install/mac-install/). - **Git**: A CLI tool to work with git repositories. For installation, refer to this [guide](https://git-scm.com/downloads) -- **Dashboard License**: We will configure Streams API using Dashboard. [Contact our team](https://tyk.io/contact/) to obtain a license or get self-managed trial license by completing the registration on our [website] +- **Dashboard License**: We will configure Streams API using Dashboard. [Contact our team](https://tyk.io/contact/) to obtain a license or get self-managed trial license by completing the registration on our [website](https://tyk.io/self-managed-trial/) - **Curl and JQ**: These tools will be used for testing. ### Instructions diff --git a/nightly/tyk-developer-portal/graphql-playground.mdx b/nightly/tyk-developer-portal/graphql-playground.mdx new file mode 100644 index 000000000..409a37b01 --- /dev/null +++ b/nightly/tyk-developer-portal/graphql-playground.mdx @@ -0,0 +1,139 @@ +--- +title: "How to Set Up the GraphQL Playground" +description: "Learn how to set up and use the GraphQL Playground in the Tyk Developer Portal" +keywords: "Tyk Developer Portal, GraphQL Playground, GraphQL API, API Documentation, Interactive API Testing" +sidebarTitle: "GraphQL Playground" +canonical: "https://tyk.io/docs/tyk-developer-portal/graphql-playground" +--- + +## Availability + +| Component | Version | Editions | +| :------------- | :---------------------- | :------------------------- | +| Developer Portal | Available since [v1.15.0](/nightly/developer-support/release-notes/portal#1-15-0-release-notes) | Enterprise | + + +## Prerequisites + +- **Dashboard License**: We will configure GraphQL API using Dashboard. [Contact our team](https://tyk.io/contact/) to obtain a license or get self-managed trial license by completing the registration on our [website](https://tyk.io/self-managed-trial/). +- **Working Tyk Environment:** You need access to a running Tyk instance that includes both the Tyk Gateway and Tyk Dashboard components. For setup instructions using Docker, please refer to the [Tyk Getting Started Guide](/nightly/getting-started/quick-start). +- Tyk Developer Portal v1.15.0 or later + +## Instructions + +Follow these steps to set up the GraphQL Playground in the Tyk Developer Portal: + +### 1. Create a GraphQL API + +1. In the **Tyk Dashboard**, create a new **GraphQL API** by + + - Navigating to **APIs > Add New API** + - In the next screen, click on **Try example** and select **Star Wars GQL API** from the list. + - Click **Use Example** to create the API. + - **Star Wars GQL API** uses [Auth Token](/nightly/api-management/authentication/bearer-token) for authentication. Copy the **Key ID** from the pop-up and save it for later use. We will set the authorization header in the Playground using this Key ID. + +2. Now, go to the **Schema** tab and download the schema. + + This schema file will be uploaded to the Developer Portal in a later step. + + GraphQL API Schema Tab + +### 2. Create the API Catalog + +The Tyk Getting Started Guide creates an API Catalog (`Public catalogue`) by default. If you don't have one, refer to this [guide](/nightly/portal/publish-api-catalog#step-1:-create-the-api-catalog) to create an API Catalog in the Developer Portal. + +### 3. Create an API Product + +1. Navigate to **Developer Portal > API Products** +2. Click **Add new API Product** + Add an API Product +3. On the **Details** tab, enter the basic product information: + Configure API Product details + - Product name: A unique product name (e.g., "Star Wars") + - Publish API product to catalogue: Select the catalog you created [previously](/nightly/#2-create-the-api-catalog) + - You can leave the other fields empty for now +4. On the **APIs** tab, select the `Star Wars GQL API` created in the [first step](/nightly/#1-create-a-graphql-api): +5. On the **Documentation** tab: + - Add your **GraphQL API endpoint URL** (e.g `http://localhost:8080/star-wars-api/`). + + + You can find the endpoint URL in the **Core Settings** tab of your GraphQL API in the Dashboard. + + + - Upload a GraphQL SDL file (in .graphql, .graphqls, .gql, or JSON format) + + By default, the GraphQL playground will introspect the schema from the endpoint if no SDL file is provided. However, if the API is protected, introspection will not work, and the schema will be rendered from the uploaded SDL file. + + GraphQL API Product Documentation Tab +6. Click **Save Changes** + +### 4. View the Playground + +1. Open your **Live Portal**. +2. Go to **Product Catalogues**, locate your GraphQL Product and Click **Docs**. + GraphQL API Docs Live Portal +3. You should now see the **GraphQL Playground**, ready for interactive query testing. + + + + To test authenticated APIs, ensure you set the required authentication headers in the Playground according to your API's authentication settings. + + For example, for the `Star Wars GQL API`, add the `Authorization` header with the value `Bearer ` where `` is the token you saved earlier. + + ```json + { + "Authorization": "Bearer YOUR_KEY_ID" + } + ``` + + + + GraphQL API Playground + +## Troubleshooting + + + + +If you encounter a `404 GraphQL API Not Found` error in the GraphQL Playground, it indicates that the Developer Portal cannot locate the specified GraphQL API. + +To resolve this issue, ensure that your API ends with a trailing slash (`/`). (e.g `http://localhost:8080/star-wars-api/`) + + +You can find the endpoint URL in the **Core Settings** tab of your GraphQL API in the Dashboard. + + + + + + +If you are seeing a `"message": "Failed to fetch"` error in the GraphQL Playground, it is likely due to CORS (Cross-Origin Resource Sharing) restrictions. To resolve this issue, follow these steps: + +Go to the Dashboard, and add the following CORS configuration to your GraphQL API settings: + +```json + "CORS": { + "enable": true, + "max_age": 24, + "allow_credentials": true, + "exposed_headers": [ + "*" + ], + "allowed_headers": [ + "*" + ], + "options_passthrough": true, + "debug": false, + "allowed_origins": [ + "http://localhost:3001" + ], + "allowed_methods": [] + }, +``` + +- Ensure that the `allowed_origins` field includes the URL of your Developer Portal (e.g., `http://localhost:3001` for local setups). + + + + +