Use GraphiQL and the SDK

GraphiQL

One easy way is to use our GraphQL IDE, GraphiQL. Select the ImpEx & API Playground version that matches the Region where your Composable Commerce Project resides.

When you get to the ImpEx page, you’ll have to log in using your Merchant Center credentials. You will have the same access to Composable Commerce Project and resources as you would through the Merchant Center. To access the IDE, select GraphQL IDE in the top menu.

Alternatively, you can go there directly with the URL:

https://impex.impex.{region}.commercetools.com/graphiql

Just remember to update the region placeholder to your own Region.

Once you logged in, you will see the following interface:

Next, let’s break down the GraphiQL interface and discuss its capabilities.

Project Selection

First, at the top of the page in the dropdown, you can see your current Project. If you want to work with data from a different Project, you can select another Project.

Query window

The left-hand side is where you enter your queries or mutations:

The autocomplete feature helps you to know the names of the fields you want to request and what is syntactically correct, like these examples:

You can select the different properties you're interested in.

It also helps with parameters when you type the open parentheses:

Once you’ve entered your query, you can run it using the play button above the query window. You can have multiple queries in your query window as long as they are all named. When you click the play button, it will display all of the queries in the window and allow you to select the one you'd like to run.

At the bottom of the page is the Query Variables window. This is where you can enter the value for the query variables you used in the queries above:

Results window

To the right of the query window is the results window. This is where you can see the response to your request:

Documentation Explorer

To the right of the results window is the Documentation Explorer window, which slides open when you click the Docs menu at the top. This allows you to browse through the schema to understand how to build your queries. It starts with the root types, but you can search or refine the types you need:

Search:

Refine:

Additional functionality

Let's explore some additional functionality:

• Prettify: formats your query to enhance readability. This is helpful if you’ve just been experimenting and making lots of changes as you refine and change your query over time.
• History displays a list of your recent queries.
• Terms: links you to the GitHub repository for the GraphiQL license page.
• Profile: returns metrics on the current query.

Here you can see the effect it has in the query window and in the results window:

Composable Commerce SDKs

How can we begin to use GraphQL in our code? Just like our Composable Commerce SDKs provide help in using the REST APIs, they also provide help in using GraphQL.

The Composable Commerce Java SDK has a module that provides GraphQL support. It generates a type-safe query and projection builder. Results can be mapped to the correct response type.

See our examples below for creating the Customer query using a sort and where parameters that we saw earlier.

GraphQLResponse<CustomerQueryResult> response = client
  .graphql()
  .query(
    GraphQL
      .customers(query ->
        query
          .sort((Collections.singletonList("id asc")))
          .where("firstName=\"Martha\"")
      )
      .projection(root -> root.results().firstName().lastName().email())
  )
  .executeBlocking()
  .getBody();

logger.info("Total Customers: " + response.getData().getTotal());
logger.info("First" + "\t" + "Last" + "\t" + "Email");
logger.info("-----" + "\t" + "----" + "\t" + "-----");
response
  .getData()
  .getResults()
  .forEach(result ->
    logger.info(
      result.getFirstName() +
      "\t" +
      result.getLastName() +
      "\t" +
      result.getEmail()
    )
  );
client.close();

Which outputs the following (modified to remove some logger info):

{
  "data": {
    "customers": {
      "results": [
        {
          "firstName": "Jennifer",
          "lastName": "Jones",
          "email": "jen@example.uk"
        },
        {
          "firstName": "Jennifer",
          "lastName": "Schmidt",
          "email": "jen@example.de"
        },
        {
          "firstName": "Jennifer",
          "lastName": "Robinson",
          "email": "jen@example.com"
        }
      ]
    }
  }
}

Test your knowledge