Building a Unified API Using GraphQL Joins

GraphQL Joins lets developers join data from two different GraphQL services to create a unified GraphQL API without needing to write custom code or modify any underlying APIs. It enables you to quickly fetch data from across databases and other GraphQL services as if they were one schema to easily mix and match your data sources. 

To create a join, you need to define the relationship between the two data sets you want to unify. Joins are typically based on a shared key between the two objects, such as an ID or name. Once the relationship is established, the query returns both data sets, allowing us to ask complex questions and receive a wealth of information in one response.

The following is a simple use case for creating a unified API with Hasura GraphQL Joins in under five minutes.

This example uses two remote GraphQL APIs, a country API and a weather API. Our goal is to find a list of countries and then connect the weather for the capitals. Both APIs are different remote GraphQL endpoints that we need to connect. Let’s get started!

In the Hasura API dashboard, we already queried the countries in the Explorer section on the left. (To learn how to add a remote schema, go here.) 

Go to the Remote Schemas dash to connect the countries and weather APIs that are GraphQL points. We start off by adding an existing GraphQL API as a remote schema. For our use case, we are adding a third-party GraphQL API containing country information. 

We will call this API "Countries."

Next, we will add a weather endpoint. You can name it anything you want, but we’ll choose “Weather” for our use case. Enter the GraphQL server URL and hit “Add.” If you need authorization headers to pass, add them in the “Additional Headers” field. 

The Weather remote schema will appear below the Countries schema.

In order to avoid conflicting definitions for “Language” in the Country and Weather fields, you need to add customization. Click on “Countries” and then go to “Modify.” Click the add button under “GraphQL Customizations.” In the Root Field Namespace, enter “countries_graph” and add “Countries” in the Prefix field, then hit Save.

Now go back to the API dash, and you will see “countries_ graph,”  “getCityby,” and “getCityByName” namespaces in the Explorer box. Click on “countries_ graph” from the dropdown menu, select “continent,” select “code,” and enter “NA” for North America. Then, under “countries,” select “capital” to fetch them.

To fetch the weather for each capital, go back to the Remote Schemas dash and select “Relationships” for the Countries endpoint. GraphQL joins relationships enable you to make nested object queries if the tables/views in your database are connected or related in the remote APIs. 

Here we will create an API that lets us fetch weather for all the country capitals of a continent that will map a relationship between a country and the weather schema.

Next, click on “Add a new relationship” and give it a name. We’ll use “GetCapitalWeather.” Then under Source Remote Schema, select “Country,” and for the Reference Remote Schema, select “Weather.”

Next, click on “Query” and “getCityByName” in the Mapping section of the dropdown menu. Select “name,” “Source Field,” and then “Capital” in the From Field dropdown menu. This will map the name parameter to the capital that's coming from the “Country” endpoint. 

Now, go back to the API dash again and click on “countries_graph” in the Explorer box. In the dropdown menu, click on “code” and type in “NA” to fetch the code of North America.

Next, scroll further down until you reach the “GetCapitalWeather” relationship we just added. Select the weather parameters you want, such as actual, minimum, or maximum temperature.

Then hit the play button to run the query to get the capital and weather of the country.

That's it. Now you can create your own unified APIs via Hasura GraphQL Joins and easily connect different remote GraphQL endpoints with just a UI and without writing any time-consuming code. 

For information about GraphQL Joins with Hasura, check out the resource links below.

• Weather API 
• Countries API 
• Adding a remote schema