GraphQL is a modern way of writing API queries that allow users to retrieve data based on query fields. This way the processing speed of the query is improved and retrieved data size is less compared to other alternatives like REST API calls.
Additional resources: GraphQL documentation
Create GraphQL exports
Important: Before you create an export from GraphQL you need to have a GraphQL connection available.
Start creating an export to your application using GraphQL in either of the following ways:
- From the Tools menu, select Flow builder. Then, click Add source.
– or –
- From the Resources menu, select Exports. Then, click + Create export.
From the Application drop-down menu, select GraphQL and your available GraphQL connection.
Edit GraphQL export details
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. If the POST method is used, the HTTP request's body will typically contain filtering or selection criteria. This information can be provided in the 'body’ field.
Consult your destination application's API documentation to determine which method is best to use for your import.
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"}.
Configure export type and preview records
There are four options for exporting data: All, Delta, Once, and Limit. All exports all your data every time your export runs. Delta only exports your modified data. Once will export all your records or data one time. Limit will export a set number of records as a test to show that your export is working properly. The default value is one, and the maximum value is 100.
Does this API use paging?
See pagination for details on which paging method to use.
Non-standard API response patterns
Some APIs may have response patterns that are unusual when compared to most APIs. Use the settings below to accommodate outlying response codes.
Path to records in HTTP response body: This optional field allows integrator.io to locate the resource (or set of resources) returned from an API call. If the HTTP response from an API contains resources at the root, then no value is necessary for this field. If the response from an API contains a deeper response structure that contains paging information, you must provide the path to the resources. If no value is provided, integrator.io assumes that the resources can be found at the root of the response. Note that the format of this path is specific to the media type. If the response is represented in JSON structure, then use "dot" notation to describe the path to your resources.
Advanced
Configure async helper: If data is exported asynchronously, check this box to select the async helper configuration.
Page size: When an export runs in the context of a data flow (meaning integrator.io sends the data from the export to an import queue), integrator.io breaks the exported data into one or more smaller pages of records. You can use the Page size field to specify how many records you want in each page of data. If you leave this field blank, the default system value is 20. There is no maximum value, but a page of data is automatically capped when it exceeds 5 MB. Most of the time, the application that you are importing data into will bottleneck the page size value. For example, NetSuite and Salesforce both document a maximum number of records that can be submitted in any single request, upon import.
Data URI template: When your flow runs but has data errors, this field allows you to verify that all the errors have a link to the original data in the export application. This field uses a handlebars template to generate the dynamic links based on the data being exported. For example, if you are exporting a customer record from Shopify, you would typically set this field to the following value: https://your-store.myshopify.com/admin/customers/{{{id}}}
Do not store retry data: Check this box if you do NOT want integrator.io to store retry data for records that fail in your flow. Storing retry data can slow down your flow's overall performance if you are processing very large numbers of records that are failing. Storing retry data also means that anyone with access to your flow's dashboard can see the retry data in clear text.
Override trace key template: Define a trace key that integrator.io will use to identify a unique record. You can use a single field such as {{{field1}}} or use a handlebar expression. For example, this syntax {{join “_” field1 field2}} will generate a trace key template field1_field2. When this field is set, you will override the platform default trace key field.
Invoke: This resource can be invoked via an HTTP request to this unique URL.
Once you have completed these settings, click Save.
Preview & send
You can preview your export data to test the requests and responses you’re getting from your applications. preview your import data to see the constructed request and a sample record that represents what integrator.io will send to the destination application.
Comments
Please sign in to leave a comment.