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
Start establishing a connection in either of the following ways:
-
From the Resources menu, select Connections. Then, click + Create connection at the top right.
– or –
- While working in a new or existing integration, you can add an application to a flow by clicking Add source or Add destination/lookup.
At this point, you’re presented with a series of options for providing GraphQL endpoint authentication.
Name (required): Provide a clear and distinguishable name. Throughout integrator.io imports and exports, you will have the option to choose this new connection, and a unique identifier will prove helpful later when selecting among a list of connections that you’ve created.
Mode (required): Select one of the following options
- Cloud to connect to a publicly accessible server application.
- On-premise to connect to a server that is publicly inaccessible and has an integrator.io agent installed on it.
Base URI (required): Provide the domain for your GraphQL endpoint. The application operates on a single endpoint (traditionally /GraphQL), and all requests are directed to this endpoint.
Authentication type (required): Select an authentication type from the list. Note that HTTP authentication types also apply to GraphQL connectors. Review the HTTP authentication type articles below to determine how to configure your authentication.
Nonstandard API rate limiter
Most APIs limit the number of requests that can be sent for a given time period. The following settings in this section of the connection help you to define the custom rate-limit settings for connecting to your API.
Wait time between HTTP requests (optional): This field lets you set the speed at which integrator.io makes requests. In other words, how long should the platform wait before making subsequent HTTP requests calls to the API? Wait time between HTTP requests should be set if the API does not implement rate-limiting and integrator.io should manually regulate call frequency. Enter the value for this field setting in milliseconds (integers, without the unit). Note that this field can be used only when the Concurrency level is set to 1.
Override HTTP status code for rate-limit errors (optional): The HTTP specification states that rate-limit response errors should return a 429 status code. Some APIs have custom rate-limit implementations that rely on other status codes or even throttle errors within the HTTP body. Enter a value if the service you are connecting to uses a status code other than 429.
Path to rate-limit error field in HTTP response body (optional): If the service you are connecting to embeds rate limit errors within the HTTP body, provide the path (JSON path or XPATH) within the response body where integrator.io should look to identify a throttled response. If there is a specific value (or set of values) that indicates rate-limit response at this path, use the Rate-limit error values setting for further instructions on how to identify this type of error.
Rate-limit error values (optional): If you provided a path in the HTTP response body field (above), then enter the exact values that the API will return to indicate rate-limit errors. Separate multiple values with a comma.
Override retry-after HTTP response header name (optional): HTTP services commonly return status code 429 when too many requests are made in a short period of time. This code typically accompanies a retry-after HTTP header response that specifies the time to wait until a successful request can be made. If the API returns this response header with a different name, specify the custom name in this setting.
HTTP response headers for rate-limit errors (optional): If the service you're connecting to signals rate-limit errors through HTTP response headers, use this field to specify the header name and value that integrator.io should check to identify a throttled response. Enter the header name in name and the value that indicates throttling in value. To evaluate a Handlebars expression against the response headers instead of matching a fixed value, click the Handlebars icon next to the value field.
Test the connection
To test the connection, you must choose an HTTP method and send a request that the endpoint can process.
HTTP method (required): Choose between POST or GET. When you switch from POST to GET, integrator.io will build the query string from the body request content.
Query (required): Enter the query to be processed by the GraphQL endpoint. The supported operation type is either query or mutation. The operation type is required unless you're using the query shorthand syntax, in which case you can't supply a name or variable definitions for your operation. The query may also include an operation name, which is required for a multi-operations query.
Operation name: 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.
Variable: Defines the JSON variables used in your query. For example, if the query is query HeroNameAndFriends($episode: Episode), define the variable as {"episode":"JEDI"}.
Before continuing, you have the opportunity to provide additional configuration information, if needed, for the GraphQL connection.
Once you have configured the GraphQL connection, you have a few options for continuing:
- Save – click this button to test the connection, commit the new connection so that it will be available to all integrations for your account
- Cancel – click to exit without saving any new changes