Schema merging

In Gloo Mesh Gateway, you can surface multiple APIs into one unified service by creating a Gloo GraphQLStitchedSchema custom resource. Gloo Mesh Gateway uses this resource to generate a stitched schema, which incorporates all the types and fields from each subschema. When clients query the route for the stitched schema, Gloo Mesh Gateway creates requests to the individual services, and then stitches the responses back together into one response to the client. For more information, see What is GraphQL stitching?.

Merge GraphQL schema link

For each API, define schema and select resolver services in your Gloo environment. Then, you can merge the GraphQL APIs together in a GraphQLStitchedSchema, and set up routing to this merged resolver.

1. For each subschema, use the following guides to create individual CRs for each API that define its schema and resolvers.

   1. Define subschema in separate ApiDoc CRs. For the Bookinfo example, you might define three CRs for the product, reviews, and ratings services.
   2. Choose how GraphQL requests are executed, and follow the guides to either proxy requests to existing GraphQL backends or define REST, gRPC, or mock resolvers for each schema.

2. Create one GraphQLStitchedSchema CR that references each GraphQL subschema. This example stitched schema for Bookinfo merges the GraphQL schema for each of the three APIs:

     apiVersion: apimanagement.gloo.solo.io/v2
   kind: GraphQLStitchedSchema
   metadata:
     name: bookinfo-stitched-schema
     namespace: bookinfo
   spec:
     subschemas:
     - schema:
         clusterName: $CLUSTER_NAME
         name: products-graphql-schema
         namespace: bookinfo
     - schema:
         clusterName: $CLUSTER_NAME
         name: ratings-graphql-schema
         namespace: bookinfo
     - schema:
         clusterName: $CLUSTER_NAME
         name: reviews-graphql-schema
         namespace: bookinfo
     

3. Create a route table that routes to a graphql.stitchedSchema destination. Specify your stitched schema resoure name in the graphql.stitchedSchema.name field, such as stitched-graphql-schema in the following examples.

   To route requests from clients that are external to your Gloo Mesh Gateway setup, you can use the following example route table.

     apiVersion: networking.gloo.solo.io/v2
   kind: RouteTable
   metadata:
     name: graphql-bookinfo
     namespace: bookinfo
   spec:
     hosts:
     - www.example.com
     http:
     - name: graphql-bookinfo
       labels: 
         route: graphql-bookinfo
         graphql: "true"
       graphql:
         stitchedSchema:
           clusterName: $CLUSTER_NAME
           name: stitched-graphql-schema
           namespace: bookinfo
       matchers:
       - uri:
           prefix: /graphql
     virtualGateways:
     - name: istio-ingressgateway
     

   To route requests from clients that are internal to your setup, such as if you use Gloo Mesh Enterprise, you can use the following example route table. Note that because the GraphQL destination references the stitched schema resource instead of a service, the value of hosts is arbitrary, as long as the request from the client app matches the host.

     apiVersion: networking.gloo.solo.io/v2
   kind: RouteTable
   metadata:
     name: graphql-bookinfo
     namespace: bookinfo
   spec:
     hosts:
     - graphql-bookinfo.internal.com
     workloadSelectors:
     - selector:
         labels:
           app: client-app
     http:
     - name: graphql-bookinfo
       labels: 
         route: graphql-bookinfo
         graphql: "true"
       graphql:
         stitchedSchema:
           clusterName: $CLUSTER_NAME
           name: bookinfo-stitched-schema
           namespace: bookinfo
       matchers:
       - uri:
           prefix: /graphql
     

4. Test routing to your stitched resolver setup.

   1. Get the external address of your ingress gateway.
      • LoadBalancer IP address:

          export INGRESS_GW_IP=$(kubectl get svc -n gloo-mesh-gateways istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
        echo $INGRESS_GW_IP
          

      • LoadBalancer hostname:

          export INGRESS_GW_IP=$(kubectl get svc -n gloo-mesh-gateways istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
        echo $INGRESS_GW_IP
          

   2. Send a request with a query to the GraphQL endpoint to verify that the request is successfully resolved by the gateway. This example command sends the request to the /graphql path and includes a query for the Bookinfo example.

        curl -vik --resolve www.example.com:443:${INGRESS_GW_IP} https://www.example.com:443/graphql \
      -d '{"query":"query { productsForHome { title ratings {reviewer numStars}} }"}'
        

   To test routing to the server, choose one of the following options:

   • Log in to your client app and send a query to the host and path to verify that the GraphQL server is reachable through the route. For the example route table, you might use this curl command:

       curl http://graphql-bookinfo.internal.com/graphql -d '{"query":"query { productsForHome { title ratings {reviewer numStars}} }"}'
       

   • Create a temporary curl pod in the bookinfo namespace and send a request to the GraphQL server from your local machine.
     1. Create the curl pod.

          kubectl run -it -n bookinfo curl --image=curlimages/curl:7.73.0 --rm  -- sh
          

     2. Send a request with a query to the GraphQL endpoint to verify that the request is successfully resolved by the gateway. This example command sends the request to the /graphql path and includes a query for the Bookinfo example.

          curl http://graphql-bookinfo.internal.com/graphql -d '{"query":"query { productsForHome { title ratings {reviewer numStars}} }"}'
          

     3. Exit the temporary pod. The pod deletes itself.

          exit
          

Reference link

For more information, see the Gloo Mesh Gateway API reference for the GraphQLStitchedSchema CR.