GraphQL Variables

You can simplify GraphQL queries and mutations by extracting data into separate variables. GraphQL variables let you re-use the same requests with different arguments.

Structure

GraphQL requests can be split into two sections: the query, and variables.

In the query section, GraphQL variables begin with the $ symbol and are declared after the query or mutation keyword, similar to passing an argument to a function.

When you declare a variable, you need to specify its type, such as CreateProductInput. This lets GraphQL know that you intend to refer to this type by this variable name later in the actual query.

Below you can see a query example that declares an $input variable and passes it to the input argument.

  mutation($input: CreateProductInput!) {
    productsCreateProduct(input: $input) { 
     # ...
    }
  }

In the variables section, the variables themselves are defined as a JSON object.

The following JSON object defines the $input variable for the query above. Refer to the CreateProductInput doc for the schema for objects of this type.

{
  "input": {
    "product": {
      "skuCode": "AX1235",
      "name": "King size bed"
    }, 
    "accountUuid": "a7353774-9795-434b-a1f8-7582b6afd345"
  }
}

Note: remember that GraphQL enforces types, so you need to refer to the documentation in this guide or in the API console when defining variables. Make sure that you use the *Input type, not the mutation type.

Revisiting the Product creation mutation

The following example uses the productsCreateProduct mutation from the previous section, but simplifies it by using variables. The result is a much cleaner and reusable mutation.

POST /graphql
Query

mutation($input: CreateProductInput!) {
  productsCreateProduct(input: $input) {
    product {
      id
      name
      skuCode
    }
    errors {
      path
      message
    }
  }
}

Variables

{
  "input": {
    "product": {
      "skuCode": "AX1235",
      "name": "King size bed"
    }, 
    "accountUuid": "a7353774-9795-434b-a1f8-7582b6afd345"
  }
}

Note: Unless you are using a client library to format the GraphQL in your API calls, you will need to ensure that both blocks above are nested inside a JSON object with respective "query" and "variables" properties in your HTTP request payload. See below if you're unsure how to format this.

JSON Response

{
  "data": {
    "productsCreateProduct": {
      "errors": [],
      "product": {
        "id": "711607e0-d9cb-41fa-9210-330dd75f79bb",
        "name": "King size bed",
        "skuCode": "AX1235"
      }
    }
  }
}

Using Variables in cURL (and other HTTP clients)

Up until now, we've only shown examples using the "query" property of the JSON object encoded as the payload of the API call. As mentioned above, it's also possible to send along variables as part of the JSON object you stringify and send in the HTTP request.

For example, if you want to perform the productsCreateProduct mutation defined above using cURL or any other HTTP client, we'd need to amend the JSON data object we pass to include two properties:

To run the cURL command from the command line, make the following substitutions, similarly to our first call:

curl -X POST \
  https://{ accountRef }.api.{ environment }.zencargo.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic { api_credentials }' \
  -d ' {
    "query": "mutation($input: CreateProductInput!) { productsCreateProduct(input: $input) { product { id name skuCode } errors { path message } } }",
    "variables": {
      "input": {
        "product": {
          "skuCode": "AX1235",
          "name": "King size bed"
        }, 
        "accountUuid": "a7353774-9795-434b-a1f8-7582b6afd345"
      }
    }
  }'

Response

{
  "data": {
    "productsCreateProduct": {
      "errors": [],
      "product": {
        "id": "711607e0-d9cb-41fa-9210-330dd75f79bb",
        "name": "King size bed",
        "skuCode": "AX1235"
      }
    }
  }
}

As you can see, we simply extend the JSON object to include the new property, "variables" and we provide valid a JSON object that matches the type defined in the documentation. The "query" property is still just the stringified GraphQL syntax.

By now, you should be reasonably familiar with the mechanics of making calls to Zencargo's GraphQL API. There are a couple of final concepts to go over before you're ready to start integrating.

Next Steps