Basic Concepts

Introduction

The best resource for GraphQL is always their documentation, which you can check out here: https://graphql.org/learn/ .

You can consume your GraphQL API as you would consume any REST API - by constructing and sending POST requests. Your requests should include an Authorization header (more on this later) and the body of the request should be in JSON format. The top-level properties of your request body JSON can be one or more of the following:

  • operationName - name of your query used for readibility reasons
  • query - the main part of your request. This is where you specify what fields you want to return.
  • variables - the dynamic parts of your query, which will be passed as arguments.

Queries

Queries are the mechanism by which you can specify what kind of data you want to get from the server. Its main components are types and fields.

Types are the entities that you want to know more about. For example, Order, Company, Product, etc. These types have pre-defined fields that you can query. For example, an Order has a shippingStatus, a subTotal and items among other fields. Similarly, a Company has a name and address, and a Product has a name, listPrice, sitePrice and siteCost.

Queries are written in the GraphQL language. The following example asks the server to return all orders, but to show only their id, shipping status, subtotal and their items' display names and site prices.

{
orders {
id
items {
displayName
sitePrice
}
shippingStatus
subTotal
}
}

The above will result in the following response:

{
"data": [
{
"id": 5040426,
"items": [
{
"displayName": "6082-5002LC-BK",
"sitePrice": 0
}
],
"shippingStatus": 1,
"subTotal": 0
},
{
"id": 5040425,
"items": [
{
"displayName": "6082-9PC-EY",
"sitePrice": 0
}
],
"shippingStatus": 1,
"subTotal": 0
}
]
}

Note format of the response. It's a JSON whose structure matches exactly what we requested in our query. This is one of the most important features of GraphQL.

Arguments and Variables

You can narrow down your results by specifying arguments in the query and passing their values as variables. For instance:

/* Query */

query ($filters: OrderFilters) {
orders(filters: $filters) {
id
items {
displayName
sitePrice
}
orderSource
subTotal
}
}

/* Variables */
{
"filters": {
"orderSource": 21
}
}

In the above example, the filters variable is transpiled in the query string and replaces the filters argument on line 4. The result will be made up only of orders which have come through channel 21 (Wholesale).

Full POST request body

The above examples are raw queries which cannot be directly sent to the server. So what would a normal POST request look like?

{
"query":"query MyOrderQuery($filters: OrderFilters) {\n orders(filters: $filters) {\n id\n items {\n displayName\n sitePrice\n }\n orderSource\n subTotal\n }\n}\n",
"variables":{"filters":{"orderSource":21}},
"operationName":"MyOrderQuery"
}

As you can see, our query has been turned into a string with special characters escaped so it doesn't break the JSON structure. You won't have to this manually though, there are many tools that do this automatically for you.

Mutations

Coming soon, stay tuned!


How did we do?