REST Configuration GraphQL

Overview

The support of GraphQL APIs (introduced in 2.2 release) is implemented on top of the SSIS+ REST Engine and enables easily querying and modifying data using a GraphQL API. The processing of the GraphQL schema allows the automatic creation of resources and fields for the corresponding Queries and Mutations. Custom queries are also supported. To learn more about GraphQL see here.

Table of Contents

Connection
Queries
Query Pagination
Mutations

Connection

The first step of connecting to a GraphQL service and processing the necessary metadata is to create a REST Connection Manager and start authoring custom configuration with GraphQL API template selected.

Then you need to specify the GraphQL service endpoint inside Base URL.

That's enough for the extraction and analysis of the GraphQL schema and the generation of the corresponding resources and fields.

Queries

To query data from a GraphQL service, use a REST Source component and select the connection manager created in the previous step. In the Resource dropdown menu you will see all entities found in the GraphQL service schema to which a query can be send.

After choosing one, all of its available fields are listed as a columns at the Columns tab.

Some GraphQL queries can be very large and complex, referencing hundreds of fields. In such cases, if selected resource exceeds 500 columns, an error message will be shown suggesting the use of < custom query > resource.

NOTE: By default all columns in REST Source are automatically selected and most of the GraphQL services have limits for Complexity and Depth. Therefore, it is possible to see the following error in Preview data, if one of these limits is hit.

When working with GraphQL it's a best practice to query only data that will be used in downstream components.

If you need to parameterize the request, you need to add parameters to the REST Source component. The parameter value has to be a valid JSON.

To learn how to configure the pagination, please see here.

In the Resource dropdown menu there is one special named < custom query >.

This resource enables specifying a custom query that can include multiple entities, fragments, inline fragments and so on:

The query itself is a value of the query parameter and all GraphQL parameters used in the query must be placed inside variables parameter.


After the query is ready, the GraphQL engine will parse it and create the needed columns based on it.

Preview-ing will send the query and parameters over the wire to the GraphQL service endpoint and the result will be displayed.

Query Pagination

In order to support paginated data retrieval, you'll need to setup a pagination. For GraphQL configurations, it's done at the resource level. It can be found at the custom configuration editor, Resource -> Read operation -> Pagination -> Next value. In the context of GraphQL configuration, there are two resources where pagination can be specified - Base and < custom query > resources.

There are four common pagination strategies supported out-of-the-box, but a custom paging can be configured, too.

Mutations

To start adding or modifying data, use the REST Destination component and link it to a REST Connection Manager GraphQL connection. In the Resource dropdown menu, you will see all entities from the GraphQL service schema to which mutation requests can be sent.

Finally do the upstream column mappings.

Additional request parameterization is done in a way similar to the REST Source component, i.e. by adding parameters with JSON values.