This post is a part of our Remote Joins series. Remote Joins in Hasura allows you to join data across tables and remote data sources. Data Federation using Hasura Remote Joins is now available from v1.3.0 stable release.

Try it out on Hasura Cloud and let us know what you think!

Data is typically sourced from different services. GraphQL Mesh allows you to use GraphQL query language to access data in remote APIs. The remote APIs can be Swagger/openapi, oData, gRPC, SOAP and others.

GraphQL Mesh can be used as a gateway to other services, or run as a local GraphQL schema that aggregates data from remote APIs.

What we are going to explore in this example is the ability to add this API source that GraphQL Mesh creates as a Remote Schema in Hasura. Going one step further we will try to establish relationships between Hasura's GraphQL API and APIs sourced via GraphQL Mesh.

GraphQL Mesh can be used as

• SDK in Node.js code
• Gateway to serve GraphQL API

We will look at using Mesh as a Gateway that exposes an endpoint that can be added as a Remote Schema in Hasura.

Initialise a GraphQL Mesh project

We can initialise a new project using yarn.

yarn init -y
yarn add graphql @graphql-mesh/cli @graphql-mesh/openapi

We are setting up the mesh CLI and adding the openapi client.

Create a config file .meshrc.yml to specify the data source and let's add the Currency Open API.

sources:
  - name: CurrencyOpenAPI
    handler:
      openapi:
        source: <path-to-open-api-schema.json>

Download the Open API Spec for this example and replace the source path appropriately. This is a spec for API served at https://api.exchangerate-api.com/v4.

Run GraphQL Mesh

Run the GraphQL Mesh instance with the following command:

yarn mesh serve

This will run a GraphQL API at http://localhost:4000.

To add this as a remote schema to the Hasura Cloud project, we will have to deploy this on a public endpoint. I'm going to make use of Codesandbox to try this out.

<!--kg-card-begin: html--><!--kg-card-end: html-->

You can create a new Sandbox/fork the above with Node.js and put in the mesh config file over there.

In your Hasura Cloud project, add the graphql endpoint from codesandbox. In the above example, it would be https://00e5c.sse.codesandbox.io/graphql. Replace this if necessary with your own forked sandbox URL.

Alright, now we have configured GraphQL Mesh to serve a GraphQL API over an existing OpenAPI spec.

Try out the GraphQL Query

query {
  getLatestBaseCurrency(baseCurrency: "USD") {
    base
    date
    rates
    timeLastUpdated
  }
}

This should fetch data from the underlying currency API.

Remote Relationship with Mesh

Assuming that we have a users table with columns id, name and currency. Let's add a remote relationship called currency_rates from inside of users table.

Now the GraphQL query to fetch this data in a single API call would look like the following:

query {
  users {
    id
    name
    currency
    currency_rates {
      date
      rates
    }
  }
}

Notice that, the nested query currency_rates come from exchange rate API following the OpenAPI spec. It will apply the filter of users.currency = currency_rates.baseCurrency, there by only giving exchange rates related to the current user's currency.

We had directly used the currency API through the OpenAPI to GraphQL library earlier and demoed it over there. The advantage of using this via GraphQL Mesh is that, you can now add multiple sources to this mesh and you get a single GraphQL endpoint for all of these different sources combined.

Should I use GraphQL Mesh as a Remote Schema?

Yes, typically the frontend clients will be querying Hasura's GraphQL Endpoint and GraphQL Mesh can be added as a Remote Schema as a way to proxy to other data sources. What Hasura gives you is a neat declarative Authorization layer on top of these GraphQL APIs and hence there's a lot less code to be written. This means that any usage of Hasura as an ORM inside Mesh will lose out on these benefits and we highly recommend using the GraphQL Mesh as a remote schema.

Uri Goldshtein, the creator of graphql-mesh gave a talk at HasuraCon earlier this year talking about how Hasura and GraphQL Mesh fits in together and can serve as a gateway to a bunch of remote API sources. Watch it below:

Check out the various examples in the github repo that can be added as a remote source to GraphQL Mesh (and it turn available for querying via Hasura).

There's another blogpost from the community talking about using GraphQL Mesh as an SDK. Do check that out as well.

Do let us know in the comments on what your typical use case for GraphQL Mesh has been and how it fits in with Hasura.