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.
Query fields
The HTTP method you choose determines how your application sends and receives data. For GraphQL, your only options are GET and POST. If the POST method is used, the HTTP request's body will typically contain filtering or selection criteria, which 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 for 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"}
.
Important
You can use Mapper 2.0 to build your variables object. After configuring your Mapper 2.0 output, add {{{jsonSerialize record}}}
in the Variables field. Then, you can reference the Mapper 2.0 output as variables in the Query field.
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.
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.
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
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
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