Link APIs

Link types, interfaces, and schemas

One of the powerful aspects of StepZen is the ability to link multiple APIs together into a single GraphQL schema and get data from these APIs in a single query.

To demonstrate this, this topic builds on the Hello World example and connects the weather type to a location type. With just one line of code for the @materializer directive, you'll connect two separate APIs, such that the location data provided by IP-API is passed to OpenWeatherMap. This allows you to get the weather based on an IP address via a single query.

Import the IP-API

Follow the steps below to import the IP-API. This API obtains IP addresses for locations:

  1. If you haven't created a /hello-stepzen folder already, create an empty project folder called hello-stepzen and navigate into that folder. Otherwise, skip this step and import directly into your /hello-stepzen folder:
mkdir hello-stepzen && cd hello-stepzen

For this example, we'll be using a template that connects to the IP-API to get geolocation data based on an IP address.

  1. Import the ip-api template into your current project:
stepzen import ip-api
  1. Name your endpoint, which creates a stepzen.config.json file:
? What would you like your endpoint to be called? (api/awesome-pronghorn)
Created /Users/my_username/hello-stepzen/stepzen.config.json
Downloading from StepZen...... done
  1. Enter your personal keys or StepZen's API keys when prompted:
? Would you like to use your personal API key? Or StepZen default keys? (Use arrow keys)
❯ Personal

Once you enter the keys, StepZen creates a new folder and adds new .graphql files to your project, similar to when we imported openweathermap for the Hello World.

Note: If you haven't haven't yet imported openweathermap then run:

stepzen import openweathermap

and follow the command prompts similarly to how you followed them when you imported ip-api.

Extend the Location type

  1. Open the file /ip-api/locationIpApi.graphql in your favorite code editor.

    To connect the IP-API to weather, you need to extend the Location type defined in this file.

  1. Add the following lines to the Location type:
weather: WeatherReport
    @materializer (query: "weatherReport")

This adds a field named weather to return the weatherReport type that was defined in the weather-report-owm.graphql from the previous step.

It then uses the StepZen custom directive @materializer to tell StepZen how to populate that field. In this case, it tells the system to use the query named weatherReport to get the data.

Since Location has fields that match the weatherReport query definition (weatherReport (latitude: Float!, longitude: Float!)), StepZen can automatically execute the correct query. The finished type looks as follows:

type Location {
  city: String
  country: String!
  currency: String
  ip: String!
  latitude: Float!
  longitude: Float!
  postalCode: String
  weather: WeatherReport @materializer(query: "weatherReport")

With just one line of code for the @materializer directive, you've connected two separate APIs, such that the location data provided by IP-API is passed to OpenWeatherMap. This allows you to get weather by IP address via a single query. Let's see this in action.

Get Weather by Location

Follow the steps below to try out the API:

  1. Run stepzen start to reload the new API and see the changes:
stepzen start
  1. Open the GraphQL query editor, navigate to the Explorer tab, and located these two queries:
  • location
  • weatherReport
  1. Add the following query using the query editor and run it to get the weather based on an IP address:
query MyQuery {
  location(ip: "") {
  weatherReport(longitude: 1.5, latitude: 1.5) {

The result looks similar to the following:

  "data": {
    "location": {
      "city": "Orlando",
      "weather": {
        "description": "clear sky",
        "feelsLike": 26.83,
        "temp": 27.69,
        "units": "degree Celsius"

You have just linked two types together. Now, as long as you can determine the IP address of the client, you'll be able to provide visitors to your site with a custom message indicating their local weather conditions.

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.