Integrate an API from WunderHub

This guide will walk you through integrating an API from WunderHub.

We're assuming you start from scratch. If you've already initiated a WunderGraph project, you can skip the first steps.

Overview#

Traditionally, you can't "just integrate" and use an API. Integrating an API usually means, you have to follow a list of manual steps to get everything working.

With WunderGraph, this is no longer the case. Think of WunderGraph as an abstraction layer on top of all APIs, making them portable and pluggable. What Docker is to Applications, WunderGraph is to APIs.

Docker made it possible to package applications as Docker images, which can be published to Docker Hub and run on any machine.

We're applying the same principle to APIs. You can package up APIs in the WunderGraph format and publish them to WunderHub.

Then, as an API consumer, you're able to integrate one or more APIs with a single command. All this is possible because we've added this abstraction layer.

Prerequisites#

To integrate your first API, we have to install the WunderGraph CLI and log in to WunderHub.

npm i -g @wundergraph/wunderctl

wunderctl login

Project Setup#

Now that you're logged in, lets init a new project and add two APIs.

wunderctl init
npm install

Adding APIs#

wunderctl add wundergraph/weather wundergraph/countries

The next step is to configure the APIs.

Open the file wundergraph.config.js and add the following configuration:

import {integrations} from "./generated/wundergraph.integrations";

const weather = integrations.wundergraph.weather({
    apiNamespace: "weather",
});

const countries = integrations.wundergraph.countries({
    apiNamespace: "countries",
});

const myApplication = new Application({
    name: "app",
    apis: [
        weather,
        countries,
    ],
});

The configuration is now complete.

To enable our IDE to enable autocompletion and intellisense, we have to generate our Virtual Graph, the virtual GraphQL Schema that is composed of all the APIs.

wunderctl generate

Now that the Virtual Graph is generated, we can define our first GraphQL Operation.

Create your first Operation#

Create a file named Weather.graphql in the ./operations directive and paste the following code:

query ($code: ID! $capital: String! @internal) {
    country: countries_country(code: $code){
        code
        name
        capital @export(as: "capital")
        weather: _join @transform(get: "weather_getCityByName.weather") {
            weather_getCityByName(name: $capital){
                weather {
                    summary {
                        title
                        description
                    }
                    temperature {
                        actual
                    }
                }
            }
        }
    }
}

This Operation loads the country with the given code and the weather for the capital city.

Running your Development Environment#

As a final step, we have to start our local development environment.

wunderctl up --debug

Well done! You've successfully integrated two APIs with WunderGraph.

Let's now call our newly created Endpoint.

curl http://localhost:9991/api/main/operations/Weather?code=DE

There we go, the weather for Berlin.

{
    "data": {
        "country": {
            "code": "DE",
            "name": "Germany",
            "capital": "Berlin",
            "weather": {
                "summary": {
                    "title": "Clouds",
                    "description": "broken clouds"
                },
                "temperature": {
                    "actual": 278.82
                }
            }
        }
    }
}

Conclusion#

That's it. You could now add more APIs, Operations, DataSources and more. Or just deploy your application to production.