Understand GraphiQL by Writing Your First Query

Several tools are available for interacting with a GraphQL server, but we will begin with the most popular tool, GraphiQL. Note how it’s spelled GraphiQL, but it’s meant to be pronounced as “graphical” — at least that’s how I’ll be referring to it. There are numerous other GraphQL clients available, but GraphiQL stands out with the excellent balance it offers in terms of features and simplicity.

GraphiQL

GraphiQL is a user-friendly browser extension for Chrome that you can use to interact with any GraphQL server. It provides a clean interface for writing and executing queries, as well as a self-documenting API.

To get started, first install GraphiQL from the Chrome Web Store. Once you've installed it, click on the browser icon, and then enter the endpoint for your Magento GraphQL server, like this:

https://magento.test/graphql

Exploring the GraphQL Interface

After installing GraphiQL and loading your Magento installation, click on the GraphiQL browser icon. Before diving into writing queries, let's familiarize ourselves with the interface.

• The top bar is where you enter your GraphQL server address. For our purposes, it will be magento.test/graphql. To access the GraphQL endpoint in Magento, simply append /graphql to the end of your URL.
• The main pane is where you'll write your GraphQL queries. Execute a query by clicking the play icon. For multiple GraphQL queries, you can add additional tabs by clicking the plus icon next to the GraphiQL text.
• The documentation explorer in the top-left corner lets you browse through documentation related to your GraphQL server.
• The show history icon displays a history of your previously executed GraphQL queries.
• The refresh icon allows you to refetch the GraphQL schema, which is helpful if your GraphQL schema changes in the background and you don't want to refresh the entire page.
• The shortkeys documentation offers insights on keyboard shortcuts, and the settings manage local settings for the GraphiQL extension.
• At the bottom, you'll find two tabs: Variables and Headers. These tabs are where you can define GraphQL query variables and headers to pass to the GraphQL server.
• Lastly, a few other icons help you prettify your query, merge fragments into queries, and copy the query to the clipboard. The results of your query will be displayed in the right pane after execution.

By understanding the GraphiQL interface, you'll find it easier to create and manage your queries as you work with Magento and its GraphQL server.

Exploring the GraphQL API

Before writing any queries, let's explore the GraphQL API provided by Magento 2. Click on the "Docs" button on the left-hand side of the GraphiQL interface.

Here, you'll find a self-documenting API with a list of all the fields available for querying. Each field has a signature showing the arguments you can pass in, as well as the data returned. Clicking on a field provides a detailed breakdown of its signature, including its description, return type, and additional information about the arguments.

The yellow text links in the docs lead to further information about specific values. These links can help you build deeper understanding of the GraphQL queries and functionality available as you navigate through the API documentation.

Writing Your First GraphQL Query

Now that you're familiar with the API, let's write a basic query to retrieve some data. In the GraphiQL interface, type the following query in the left pane:

{
  availableStores {
    base_url
  }
}

This query asks the GraphQL server to return the base_url of all available stores. Click the "Run" button (or press Ctrl+Enter) to execute the query.

The server will return the data in JSON format in the right pane:

{
  "data": {
    "availableStores": [
      {
        "base_url": "https://magento.test/"
      }
    ]
  }
}

Congrats! You've successfully written and executed your first GraphQL query.