> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# GraphQL Request Structure

Plan: Developer Foundations

Lesson 10 of 28 · 30 min

## Fundamentals of GraphQL

The basic GraphQL query structure looks like this:

```graphql showLineNumbers={false}
root{
  field{
    subfield{
      subfield{
        ...
      }
    }
  }
}
```

The **root** tells the GraphQL server what kind of request you are making. There are two possible roots in the Storefront GraphQL API: Query and Mutation.

* **A query will only return the data you request.** For example, you want to know what the names of the categories are for a storefront.
* **A mutation will make a change to the storefront.** For example, you want to add a shipping consignment to a customer's order.

The fields and subfields define the objects for which you need to gather data. Adding subfields to a request will result in an array of items, allowing you to define your query to the exact information you need.

You can also add arguments to each field and subfield in a GraphQL request. This is how you can save time with GraphQL instead of making multiple REST API calls. The example below shows how you can use an argument to gather information about a specific category.

```graphql showLineNumbers={false}
query{
  site{
    category(entityId:22){
      name
    }
  }
}
```

## Edges and Nodes

Edges and nodes are fields that will be used anywhere we have a list of objects. These fields allow you to specify the data you want to be returned.

An **edge** is a field that connects a list of data to different nodes to allow you to specify what data you want to be returned.

A **node** is an edge type that is used to identify what data you want to be returned. Under the node field you can ask for data such as name, entityId, description, price, etc.

One way to think about the connection between edges and nodes is this – an edge is the page of data, and the node is identifying what data is on that page.

### Example

```graphql showLineNumbers={false}
query{
  site{
    products{
      edges{
        node{
          entityId
          name
          sku
        }
      }
    }
  }
}
```

The example query above is asking GraphQL to return a list (edge) of products in the store. The query also specifies that the list should only contain the `entityId`, `name`, and `sku` (nodes) for each product.

### Variables

Variables can be used to create dynamic queries and mutations. They are passed like arguments to a function allowing the arguments to be extracted as variables from queries and mutations.

You need to do three things to start working with variables:

1. Replace the static value in the query with `$variableName`
2. Declare `$variableName` as one of the variables accepted by the query
3. Pass `variableName:` value in the separate, transport-specific (usually JSON) variables dictionary

For example, the variable below is written in the variables dictionary:

```json showLineNumbers={false}
{
  "createCartInput": {
    "lineItems": [
      {
        "quantity": 1,
        "productEntityId": 111
      }
    ]
  }
}
```

When you write the variable into the mutation, it will look like this:

```graphql showLineNumbers={false}
mutation createCartSimple($createCartInput: CreateCartInput!) {
  cart {
    createCart(input: $createCartInput) {
      cart {
        entityId
        lineItems {
          physicalItems {
            name
            quantity
          }
        }
      }
    }
  }
}
```

The variable definition looks like `$createCartInput` in the mutation above. It lists all of the variables, prefixed by `$`, followed by their type, in this case `createCartInput`. Variable definitions can be optional or required. The variable definition in the example above is required because we include a `!` next to the definition.

## Aliases

Aliases let you rename the result of a field to anything you want.

![Image](/_fern-files/bigcommerce.docs.buildwithfern.com/7ece7fe2a358bac1748685f4d433a508d891fb352ba2c12a0801695ed55eb19f/assets/learn/graphql-storefront-api/gl4.png)

If we are interested in the Name but want it to be called `productName` in the response instead, we can alias the name.

`productName: name`

When you do this, you change the key on the response.

![Response](/_fern-img/cc88d0dcde500b0544194f4cd0db17ea008c5c51f6ce36bf8d2a5e4badae078a.webp)

Aliases are useful for light cases when you need to map between two APIs. GraphQL will conform to what you need on the receiving end.

### Fragments

A GraphQL fragment is a reusable unit of a query. If you are going to request the same fields several times, you can use fragments which will save you duplication. Fragments are used for reusing things in several places. You can construct sets of fields and include them in queries where you need to.

![Image](/_fern-files/bigcommerce.docs.buildwithfern.com/27f26e8c3782966e0204e0def5c7b773f206961098ddd91f8b415f6bd8dd238c/assets/learn/graphql-storefront-api/fragmentExample.png)

Fragments consist of three components:

* **Name**: This is the unique name of the fragment (each fragment can have its own name).
* **TypeName**: The type of object the fragment is going to be used on. It indicates which nested object, from the GraphQL schema, the fragment is created on.
* **Body**: The last part is the body of the fragment. The body of the fragment defines the fields that will be queried on.
  Use the fragment within the query by using the `...` operator and providing the fragment's name.
  Example:  `...PriceFields`

By using product (as opposed to products) for a single product, you can indicate the product ID of interest using the entityId and since we don't want to retype everything, you can use the fragment to return the fields we want.

![Image](/_fern-img/609bf74a6a57bb6cf118ac968841f0c8cb2f70bf6c28de7eeeb9d3748157355e.webp)

## Resources

* [Aliases](https://graphql.org/learn/queries/#aliases)
* [Fragments](https://graphql.org/learn/queries/#fragments)
* [Pagination](/developer/docs/storefront/guides/graphql-storefront-api#pagination)