Import a Prebuilt Schema Template

Quickly build GraphQL APIs connected to popular services

The quickest way to get started with StepZen is to use one of our templates. These just provide a way to jumpstart your API code by providing pre-built schemas for a number of popular APIs. Let's walk through using the OpenWeatherMap template. This template pulls weather data from the OpenWeatherMap API. We'll even look at how to connect this with a second API that will allow us to get weather for a location based upon the user's IP address.

If you'd prefer to jump right into building your own custom schema, check out connecting backends.

Import the OpenWeatherMap Template

First, create an empty project folder called hello-stepzen and cd into that folder.

mkdir hello-stepzen && cd hello-stepzen

Next, import the openweathermap API template.

stepzen import openweathermap

You'll be prompted to give it the API a name, which must be in the pattern of folder-name/endpoint-name. The CLI will suggest a random name as in the following:

What would you like your endpoint to be called? (api/undercooked-lion)

Let's enter api/hello-world for our folder name and endpoint name.

We'll explore the code contained in this template in a moment, but, for now, let's get the sample running so that we can test the API using stepzen start.

You'll then be prompted to use either your personal keys or StepZen's API keys:

? Would you like to use your personal API key? Or StepZen default keys? (Use arr
ow keys)
❯ Personal 
  StepZen 

Let's use StepZen's for now. You'll then see:

Generating schemas...... done
Successfully imported 1 schemas from StepZen

Now, run this command:

stepzen start

This command will first upload and deploy your code to StepZen. You will see a message in your command line like the following:

Watching /Users/brian/Documents/projects/hello-stepzen for GraphQL changes

http://localhost:5000/api/hello-world

Deploying to StepZen...... done

Successfully deployed api/hello-world at 1:00:06 PM

Your endpoint is available at https://biggs.stepzen.net/api/hello-world/__graphql

stepzen start will continue to watch for changes to the schema code and upload them, allowing you to test your changes immediately. It will also launch a GraphQL query explorer in your default browser.

GraphiQL

Click on the "Code Explorer" button to see the different queries and fields within the new schema. At this point, we only have one query: weathereport. Clicking on it will create a query within the editor. Click on any fields you would like to add to your query. For example, we can select them all for a query like the following:

query MyQuery {
  weatherReport(latitude: 1.5, longitude: 1.5) {
    description
    feelsLike
    latitude
    longitude
    temp
    units
    date
  }
}

To run the query, click on the "play" button (▶️). You should get a result like the following:

{
  "data": {
    "weatherReport": {
      "date": "2021-05-03",
      "description": "moderate rain",
      "feelsLike": 31.9,
      "latitude": 1.5,
      "longitude": 1.5,
      "temp": 28.11,
      "units": "degree Celsius"
    }
  }
}

Congratulations, you already launched your first GraphQL API using StepZen and ran your first query!

What Are API Templates?

API Templates are pre-made GraphQL schemas configured with types, queries, and backends, designed to be combined, customized, and extended and help you quickly create your GraphQL API. In this case, the StepZen CLI (stepzen import) imports the openweathermap template from our GitHub repository of templates. It gets the current weather conditions from the OpenWeatherMap API based on latitude/longitude.

To learn about building with API Templates, browse the Web Gallery or see all the API Templates on GitHub.

You do not need to use an API template to build your StepZen schema, but it can give you a nice head start if you are connecting one of a number of common backend APIs.

Exploring the Code

Let's take a quick look at the code to better understand how StepZen works. The schema is currently made up of two files:

/openweathermap/weather-report-owm.graphql

This file contains the schema type (WeatherReport) and query (weatherReport) that we saw in the query editor earlier when we constructed a query and got a result. The WeatherReport type defines different fields that make up its data and the type of data it will contain (e.g. Float, Date, String, etc.).

The Query type defines the different queries that are available on this type and the arguments that can be passed to them. We only have one query (weatherReport) that accepts longitude and latitude arguments and returns a WeatherReport object as a result. The @connector code is a custom StepZen Graphql directive that tells StepZen to use our built-in OpenWeatherMap connector. We'll dig more into the StepZen's custom directives in a later tutorial.

type WeatherReport {
  date: Date!
  latitude: Float!
  longitude: Float!
  temp: Float
  feelsLike: Float
  description: String
  units: String
}

type Query {
  weatherReport(latitude: Float!, longitude: Float!): WeatherReport
    @connector(
      type: "__openweathermap_weather_location_connector__"
      configuration: "owm_default"
    )
}

All of the types and queries that make up your StepZen schema will be contained in .graphql files like this one.

index.graphql

This file is essentially the glue that pulls together all the other .graphql files in your schema. We currently only have one other file, so this is the only one that it lists.

schema @sdl(files: ["openweathermap/weather-report-owm.graphql"]) {
  query: Query
}

As we add additional .graphql files with more types and queries, we'll need to add them to the list of files within index.graphql.

What about stepzen.config.json?

You may have noticed this other file in there. Technically, this isn't a requirement for a StepZen schema. Rather, it is a file written out by the StepZen CLI to store settings and configuration. Remember earlier when the CLI asked us what we want to name our API? This is where that information was ultimately stored.

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.