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 in GraphQL
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.
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 } } }
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 ($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}
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 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 } }
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):
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} } } }
Comments
Please sign in to leave a comment.