GraphQL API

This document gives an overview of GraphQL API.

The commercetools platform provides a GraphQL API.

Supported entities

It currently supports following entities:

Query GraphQL

You can access the GraphQL endpoint with following URL:

https://api.commercetools.com/{projectKey}/graphql

It accepts POST requests with following fields in a JSON body:

  • query - String - GraphQL query as a string
  • variables - Object - Optional - containing JSON object that defines variables for your query
  • operationName - String - Optional - the name of the operation, in case you defined several of them in the query

Here is an example of a GraphQL query:

$ curl -X POST https://api.commercetools.com/my-shop/graphql \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ..." \
-d '{"query": "query ($sku: String!) {product(sku: $sku) {id version}}", "variables": {"sku": "SKU-123"}}'

Interactive GraphQL console

In order to explore the GraphQL API, you can use an interactive GraphiQL environment which is available as a part of Impex.

Here is a short demonstration if the GraphiQL tool and how you can use it to discover the schema:

GraphiQL demonstration

Product attributes and custom fields

Product attributes and custom fields are dynamic fields, customized for the needs of each project.

To access them, you have two possibilities:

  • typed graphQL fields
  • raw graphQL fields

Typed product attributes and types custom fields

Product attributes as well as custom fields are dynamically generated for project’s GraphQL schema, depending on your ProductType and Type definitions, in an eventually consistent fashion.

Typed graphQL fields are good if you need to work on defined types, but using them adds a performance overhead.

Pseudo-example how to use typed product attributes:

fragment variantFields on ProductVariant {
  sku
  attributes {
    ... on <MyProductType>ProductType {
      <referenceFieldA> {
        id
      }
      <fieldB> {
        value
      }
    }
  }
}

Pseudo-example how to use typed custom fields:

fragment customFields on ProducePrice {
  custom {
    customFields {
      ... on <MyType>Type {
        <referenceFieldA> {
          id
        }
        <fieldB> {
          value
        }
      }
    }
  }
}

Raw product attributes and raw custom fields

Raw GraphQL fields provide the values as raw json that you have to parse yourself, but they are always consistent and they are performing well.

Pseudo-example how to use typed product attributes:

fragment variantFields on ProductVariant {
  sku
  attributesRaw {
    name
    value
  }
}

Pseudo-example how to use typed custom fields:

fragment customFields on ProducePrice {
  custom {
    customFieldsRaw {
      name
      value
    }
  }
}

Reference Expansion

The GraphQL API supports Reference Expansion, just like the HTTP API.

By convention, the GraphQL API offers two fields for each expandable reference:

  • <fieldName>Ref - Reference
  • <fieldName> - Optional
    The expanded resource.
    Returns null if the referenced resource is not found.

Expanding a reference in the GraphQL API impacts the performance of the request. You can use the GraphiQL’s Profiling function to measure the impact for your project:

GraphiQL profiling