Hello World: Create & Query Your First API

How to build and query your first GraphQL API using the StepZen CLI

There are a couple of ways to get started quickly with StepZen:

  • If you signed up and have not explored the GraphQL Studio, this Hello World topic is for you. It describes how to create a simple StepZen project, deploy a GraphQL API, query the API in minutes, and explore the schema.

  • If you have schemas you created in the GraphQL Studio, get started with the pre-built GraphQL Schemas you downloaded from the GraphQL Studio. See Work With Schemas Downloaded from the GraphQL Studio for more information.

Prepare to Create and Query a GraphQL API in Minutes

Before continuing, ensure you have installed and set up the StepZen CLI.

You can use the StepZen CLI to import a pre-made GraphQL schema (i.e., a schema template). For this Hello World example, you'll use this capability (i.e., the stepzen import command) with a schema we've made for you to quickly create a GraphQL API that connects two APIs to backend data sources.

  • OpenWeatherMapAPI: Returns weather data from the OpenWeatherMap API.
  • IP API: Provides an IP address for a given geolocation.

When combined in your GraphQL API, this allows you to get weather data for a location by using the user's IP address.

Afterwards, you can explore the code to see how the schema came together. In Link APIs you'll see how to configure your GraphQL schema file (SDL) to easily link the two APIs such that the data from one API becomes input for the second. And all of this is done by configuring your GraphQL Schema file, without any need for coding.

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

Import the OpenWeatherMap Schema

Follow the steps below to import the OpenWeatherMap GraphQL schema:

  1. Create an empty project folder called hello-stepzen and navigate into that folder.

    mkdir hello-stepzen && cd hello-stepzen
  2. Import the openweathermap API template:

    stepzen import openweathermap
  3. Enter an API name when prompted:

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

    The CLI suggests a random name such as api/undercooked-lion, but for this exercise, enter api/hello-world for the folder name and endpoint name:

    api/hello-world

    Note: The API name must follow the pattern: folder-name/endpoint-name.

    You'll explore the code contained in this GraphQL schema in a moment, but for now, get the sample running so that you can test the API using stepzen start.

  4. Specify the keys to use when prompted. StepZen asks to use either your personal keys or StepZen's API keys. For this example, use the latter by pressing the down arrow to select StepZen:

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

    This generates the following output:

    Generating schemas...... done
    Successfully imported 1 schemas from StepZen
  5. Upload and deploy your code to StepZen:

    stepzen start

    A message similar to the following is displayed:

    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 continues to watch for changes to the schema code and upload them, enabling you to test your changes immediately. The message in your command line returns the endpoint for your newly created GraphQL endpoint, which is https://biggs.stepzen.net/api/hello-world/__graphql in the example above.

Use the GraphQL Query Explorer

stepzen start also launches a GraphQL query explorer in your default browser on localhost, which is a local proxy to your GraphQL endpoint. This local proxy can only be used to explore the API with GraphiQL. For network requests, you must always use the actual GraphQL endpoint that's created when you run stepzen start:

GraphiQL

The GraphQL query explorer is partitioned into three sections:

  • Explorer: Lists and allows selection of API schemas. Note: This section isn't shown by default. Click on Explorer to display this section.
  • Editor: Allows you to view and edits APIs.
  • Results: Displays the results returned from executing your APIs.

Prepare a Query

Click the Explorer button near the top of the GraphQL query explorer to see the different queries and fields within the new schema.

In this example, there is only one query: weathereport. Click on any of the query parameter fields in the Explorer section that you would like to add to your query, and the query auto-updates within the Editor. For example, you can select them all to create a query like the following:

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

Note: If you want to import a new API, first close the existing one by returning to the command line and pressing Ctrl + C to stop the stepzen start process. Then, follow the steps above again to import your new API.

When you run stepzen start again, it closes the existing GraphQL query explorer instance in your browser and opens a new one.

Run a Query

To run the query, click Play. A result similar to the following is displayed.

{
  "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've launched your first GraphQL API using StepZen and run your first query! Navigate to Explore Hello World Code to get additional details about the code.

Want to Add Another API?

If you want to import a new API:

  1. First return to the command line and press Ctrl + C to stop the stepzen start process. Then, follow the steps above to import your new API.

  2. When you run stepzen start again, it closes the GraphQL query explorer instance in your browser and opens a new one.

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.