Working with GraphQL in xDI

To design a Semarchy xDI GraphQL workflow, you first need to design and configure GraphQL metadata. Afterwards, add it to a mapping, and map its fields to datastores.

Metadata structure

GraphQL metadata is a tree structure with nested nodes. Each node has its own parameters to control aspects of the integration flow. The overall structure is as follows:

  • The metadata object holds a top-level metadata node with base parameters.

  • The top-level node holds one or more query nodes, which represent a query or a mutation.

  • Query nodes hold responses.

  • Response nodes contain a JSON root node.

  • The JSON root node must contain a data JSON object, which itself holds further JSON objects, arrays, or values representing the expected successful response.

  • The JSON root node can also contain an error JSON array, which holds error objects structured as in the GraphQL specification.

Request output and error handling are managed in mappings.

Mappings

To design an integration flow around GraphQL, drag a query node to an xDI mapping. This operation always performs the same query against the endpoint defined in the metadata.

For example, take the following nested metadata structure:

Top-level node (http://localhost:4000/graphQL)
└── Query node (GetCustomer)
    └── Response node
        └── JSON structure

Dragging and dropping the GetCustomer query to a mapping creates an object that sends a GetCustomer GraphQL request to http://localhost:4000/graphQL.

Mappings behave like any other HTTP-based component. You can chain GraphQL calls, add filters, or send the error array to a logging datastore to keep observability high.

Input and output

When you add a GraphQL query to a mapping, you can map its nested JSON responses like any other mapping object.

  • Request nodes can take inputs from other sources to assign variables. Map data from a datastore such as file or database fields.

  • Responses and their parameters create output data that you can map to a datastore.

If you do not map input data to the query, add a dummy object as a mapping starting point.

Integration templates

In a mapping, you can also open the GraphQL metadata integration template to control more parameters, such as partial response and error handling.