Docs/guide graphiql

apps/docs/docs/how-to-guides/faststore-api/using-graphiql-to-explore-the-faststore-api.mdx

@@ -0,0 +1,116 @@
+---
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Using GraphiQL to explore the FastStore API
+
+[GraphiQL](https://github.com/graphql/graphiql) is an Integrated Development Environment (IDE) for [GraphQL](https://graphql.org/). You can run GraphiQL on your browser in order to try out queries and mutations in a GraphQL API.
+
+You can explore your store's GraphQL data layer by running a local server of your project.
+
+## Getting started
+
+Follow these steps to run a local server and access GraphiQL:
+1. Open the terminal and change to your FastStore project directory.
+2. Install dependencies by running the command `yarn`.
+1. Run the command `yarn develop`.
+2. Once the local server is up and running, access this address on your browser:
+```
+http://localhost:8000/__graphql
+```
+
+![graphiql home](https://vtexhelp.vtexassets.com/assets/docs/src/_te1%20graphiql%20jun2022___94e3a61397f80a3dae952941d2bb32cc.png)
+
+:::caution
+If these steps do not work for you, you may not have the latest version of the `@faststore/api` dependency installed. You can reinstall it by running the command `yarn` in your project.
+:::
+
+## Building queries
+
+You can use the text box on the left side to type queries and mutations. When you are done, click the <img alt="Execute query" className="inline w-6" src="https://vtexhelp.vtexassets.com/assets/docs/src/executeQuery___7272503777684ec305975f94ff9f3698.png"/> **Execute Query** button or press `Ctrl + Enter` to submit your request.
+
+:::danger
+If you are experiencing dificulties running queries in GraphiQL with [gatsby.store](https://github.com/vtex-sites/gatsby.store), try installing and using [graphql-playground](https://github.com/graphql/graphql-playground).
+:::
+
+![graphiql query](https://vtexhelp.vtexassets.com/assets/docs/src/t2%20graphiql%20jun2022___6d2398d64e34bdacd154f807df1ddf97.png)
+
+:::info
+If you are not sure what arguments or fields are allowed or required by some query, press `Ctrl + space` to use autocomplete. It will show you all available options. You can also use the `Explorer` tab. Learn more about it in [Exploring queries interactively](#exploring-queries-interactively).
+:::
+
+## Exploring queries interactively
+
+Click the `Explorer` button to open the GraphiQL Explorer and tick the desired fields and inputs to build queries interactively. By doing so, you may avoid the repetitive process of manually inputting these values.
+
+![graphiql explorer](https://vtexhelp.vtexassets.com/assets/docs/src/_te3%20graphiql%20jun2022___1ecd4aa2fb20395eb6262e704ef48268.png)
+
+:::caution
+Note that the FastStore API extends the data layer provided by the framework you use (e.g., Gatsby, Next.js). This data layer may contain many other types and fields that are displayed in GraphiQL. To know what elements are actually part of the FastStore API, check the reference docs for [queries](https://www.faststore.dev/reference/api/queries) or [mutations](https://www.faststore.dev/reference/api/mutations).
+
+Check your framework documentation and learn more about [how Gatsby deals with GraphQL query options](https://www.gatsbyjs.com/docs/graphql-reference/) or [Data fetching in Next.js](https://nextjs.org/docs/basic-features/data-fetching/overview).
+:::
+
+## Passing arguments
+
+You can click `QUERY VARIABLES` at the bottom of the screen to open another text box where you can organize the query variables in JSON format.
+
+Setting the **Query Variables** section is recommended when a query has multiple arguments. Inside the query/mutation parentheses, define the names and types of the variables. Note that the variable names must be preceded by a dollar sign (`$`). 
+
+In the following example, `MyFirstQuery` accepts two variables: `$first` of type `Int` and `$after` of type `String`. The exclamation mark after the type indicates that the corresponding variable is required.
+
+Create a JSON object on the Query Variables pane with your variable names and values as key-value pairs.
+
+![graphiql variables](https://vtexhelp.vtexassets.com/assets/docs/src/_te4%20graphiql%20jun2022___9134ece78377ac52bf839486d0de9aa9.png)
+
+See an example of how to code this:
+
+<Tabs>
+
+<TabItem value="query" label="Query" default>
+
+```graphql
+query ExampleWithVariables ($first: Int!, $after: String) {
+  allProducts (first: $first, after: $after) {
+    edges {
+      node {
+        name
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+
+<TabItem value="variables" label="Variables" default>
+
+```json
+{
+  "first": 5,
+  "after": "10"
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+## Consulting documentation
+
+You can also learn more about the types and fields available by opening up the `DOCS` tab in the upper right corner. There you can search or browse through FastStore API queries, mutations and types in order to read the corresponding descriptions.
+
+![graphiql docs](https://vtexhelp.vtexassets.com/assets/docs/src/_te5%20graphiql%20jun2022___1040a138b8450b6be3d6e3765ac46289.png)
+
+:::caution
+VTEX is continuously working to ensure that the FastStore API types and fields are documented and available via GraphiQL. However, other APIs and frameworks (e.g., Gatsby, Next.js) may not necessarily be documented this way.
+:::
+
+## Checking your query history
+
+ The **History** panel provides a list of all previously executed queries. Click the query summary presented on the **History** panel to view it in the editor.
+
+![graphiql history](https://vtexhelp.vtexassets.com/assets/docs/src/te6%20graphiql%20jun2022___c6de0eb13aa2c21637def56f3be650b4.png)