Build GraphQL queries

GraphQL is a query language for your API and a server-side runtime for executing queries using a type system you define for your data. In integrator.io, you can use GraphQL to connect to application endpoints and gather data based on your queries.

Contents

• Query fields in GraphQL
• Types and basic queries
  • Shorthand syntax query
  • Query with a blank Operation name
  • Mutation operation
  • Multiple queries with operation names

Query fields in GraphQL

Query fields

The HTTP method you choose determines how you’re sending and receiving data from your application. For GraphQL, your only options are GET and POST. The HTTP request's body will typically contain filtering or selection criteria if the POST method is used. This information can be provided in the body field.

The Query field defines the request the GraphQL server is processing. If you use the query shorthand syntax (omitting the operation type and name), you can’t supply a name or any variable definitions for your operation. Note that the operation name is required if you’re writing a multi-operation query.

Building a GraphQL query is fairly straightforward once you understand the data schema and your application’s GraphQL endpoint API documentation. You can build a query during a connection, export, or import. Either way, the query structures stay the same.

The Operation name field is only required if your query has two or more operations. A request can only execute one operation at a time.

The operation name is a meaningful and explicit name for your operation. Its use is encouraged because it is helpful for debugging and server-side logging. When something goes wrong, such as errors in your network logs or in your GraphQL server logs, it's easier to identify a query in your codebase by name instead of deciphering the contents. Think of it as a function name in your favorite programming language.

The Variable field defines the JSON variables used in your query. For example, if the query is query HeroNameAndFriends($episode: Episode), define the variable as {"episode":"JEDI"}.

Types and basic queries

Every GraphQL-enabled application uses an API guide to define the data schema you can query. Then, when queries come in, they’re validated and executed against that schema by the endpoint application.

For example, you may want to use GraphQL to query data from your Shopify store. To do so, set up an endpoint connection to GraphQL using your Shopify API base URI and the GraphQL endpoint.

Supported operation types are either query or mutation. Mutations allow you to modify data in your application.

Shopify’s API documents suggest that you use the POST HTTP method, but always check your application’s API documents to determine whether you should use POST or GET.

Shopify URL and POST requirements

https://{store_name}.myshopify.com/admin/api/2022-04/graphql.json

Tip: Check with your application to determine if they have a GraphQL endpoint. You’ll need to use your application-specific GraphQL endpoint API documentation to learn more. The examples below are based on Shopify’s GraphQL API documentation.

Shorthand syntax query

This example query requests the first 5 price lists with the ID, name, and currency information. Your query's pageInfo and endCursor let you know if the list has more than one "page" as determined by your cursor-based pagination and tells you when your list ends.

Query

{
  priceLists(first: 5) {
    edges {               
    node {id,name,currency}            
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Preview data results for shorthand syntax query

Query with a blank operation name

Below is an example of a Query operation that includes a variable, a GraphQL query filter, and a pagination handlebar.

Tip: Don’t forget that your query and variable definitions are in two different fields.

Query with no operation name and variable

Pagination

query ($var: Int!) 
{
  customers(first: $var, query:"accepts_marketing:true" {{#if export.http.paging.token}}, after: "{{export.http.paging.token}}" {{/if}}) {
  pageInfo {hasNextPage endCursor}            
  edges {               
    node {id,firstName,lastName}            
    }
  }
}

Variable input

{"var":5}

Preview data results for query with no operation name

Mutation operation

Below is an example of a Mutation operation including one variable.

Tip: Don’t forget that your query and variable definitions are in two different fields.

Mutation query

mutation customerCreate($input: CustomerInput!) {
  customerCreate(input: $input) {
    userErrors { 
      field 
      message 
    }
    customer {
      id
      phone
      email
      acceptsMarketing
      firstName
      lastName
    }
  }
}

Variable field (You must provide the variable in a valid JSON-format):

{
  "input": {
    "email": "{{random 'crypto' 8}}@random.com",
    "phone": "{{record.launch.launch_site.site_phoneNumber}}",
    "firstName": "{{record.launch.launch_site.site_name}}",
    "lastName": "{{record.launch.launch_site.site_id}}",
    "acceptsMarketing": true
  }
}

Preview data results for mutation operation

Multiple queries with operation names

GraphQL allows multiple operations inside one query; however, you must provide an operation name. You can either provide a static value or set it during run time using the Advanced field editor (AFE) and handlebars. Query with multiple operations (getPriceLists and getCustomers):

Price lists operation name

Get customers operation name

Query

query getPriceLists{
  priceLists(first: 2) {
    edges {
    node {id, name, currency}
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

query getCustomers{
  customers(first: 3) {
  pageInfo {hasNextPage endCursor}
  edges {
    node {id}
    }
  }
}

Preview data results for priceLists

Preview data results for getCustomers