Start a Project with a Downloaded Schema from the GraphQL Studio

Start coding a project with a downloaded schema from the GraphQL Studio

There's no need to sign up for a StepZen account to explore how StepZen helps you build and run your first GraphQL API.

Inside the StepZen GraphQL Studio, you can select from pre-built APIs for popular services, run queries and get responses right in the GraphQL Studio, and overall explore their potential to power your apps. This video summarizes some of the features: Let's Explore the Studio

As you can see, you can explore and test queries in GraphQL Studio prior to signing up, taking what you've built, and extending it with the StepZen CLI.

Note: For basic instructions how to import schemas downloaded from the GraphQL Studio, see Work With Schemas Downloaded from the GraphQL Studio. Or follow this tutorial for a walk through using an example.

Let's get started! In this tutorial, we select the combination named Local Currency by IP.

  1. In the GraphQL Studio we selected the combination: Local Currency by IP

  2. Click Publish, then Download and Build. The 'stepzen.zip' file is downloaded to your computer.

  3. Unzip the files. They have the following structure:

    .
    ├── index.graphql
    ├── config.yaml
    ├── _ip-api
    │   └── ip-api.graphql
    └──  _frankfurter
         └── frankfurter.graphql

Move them to a folder named stepzen to keep them easily identifiable within the larger structures of your project.

Understanding your project files

index.graphql

Inside index.graphql, you'll see this code:

schema
  @sdl(files: ["frankfurter/frankfurter.graphql", "ip-api/ip-api.graphql"]) {
  query: Query
}

This is the code that tells StepZen which pre-built schemas to include in your unified GraphQL API. If you make new schemas and want to add new data sources to your GraphQL endpoint, you must define them in this file.

config.yaml

Inside config.yaml, you'll see:

configurationset:
  - configuration:
      name: frankfurter_config
  - configuration:
      name: ip-api_config

The configuration names are used in the schema code to specify secrets and keys and keep them separate from your code. If you used your own data (and not mock data) to craft your API in the GraphQL Studio, your API keys are defined in the apiname_config file. You would specify them here in the config.yaml file, enabling StepZen to 'find' them when it runs your endpoint.

For more detail about configuration files, see Configuration and Keys.

ip-api/ and frankfurter/ folders

The ip-api and frankfurter folders hold the GraphQL schemas that define the queries you can run -- you can edit these to fit your needs. New to writing GraphQL schemas? For more about StepZen's configuration-driven approach, see Design A GraphQL Schema

Get up & running on StepZen

Now it's time to get your endpoint up and running (locally, at localhost:5000, so you can test and iterate right on your local machine -- and at its deployed URL).

Install the StepZen CLI

If you haven't before, sign up for a StepZen account and install the StepZen CLI.

  1. Navigate to the folder you downloaded, and run stepzen start from the terminal. You are prompted to name your endpoint:
What would you like your endpoint to be called? (api/your-api-name)
  1. Accept the suggestion or write your own API name.

Your terminal outputs a message like this as the CLI uploads and deploys your endpoint:

Watching ~/Downloads/stepzen for GraphQL changes

http://localhost:5000/api/your-api-name

Deploying to StepZen...... done

Successfully deployed api/your-api-name at 2:14:31 PM

Your endpoint is available at https://username.stepzen.net/api/your-api-name/__graphql

Using your GraphQL API endpoints on localhost and in the cloud

Your endpoint is deployed to the StepZen cloud.

The proxy available locally and running in a GraphiQL editor on your machine takes the format http://localhost:5000/api/your-api-name. Use this URL to test and query your endpoint locally.

A different endpoint is deployed on StepZen in the cloud. It takes the form: https://username.stepzen.net/api/your-api-name/__graphql. This endpoint is the one your schemas are deployed to in StepZen's cloud. This is the endpoint you'll consume with fetch, axios, urql, or whatever tool you choose.

Query your API

  1. Navigate to your localhost API running in the GraphiQL browser: http://localhost:5000/api/your-api-name

  2. Test your API by running queries like this in the GraphiQL editor:

query MyQuery {
  ipApi_stepzen_request {
    clientIp
  }
  frankfurter_latest_rates(amount: 1.5, from: "USD", to: "EUR") {
    amount
    base
    date
    rates
  }
}

to return JSON:

{
  "data": {
    "frankfurter_latest_rates": {
      "amount": 1.5,
      "base": "USD",
      "date": "2021-10-27",
      "rates": {
        "EUR": 1.2912
      }
    },
    "ipApi_stepzen_request": {
      "clientIp": "80.200.56.930"
    }
  }
}

Now go ahead, play around with your API! Insert the StepZen folder you downloaded from the GraphQL Studio into any project you like, and your GraphQL endpoint is easily available in your user interface!

For examples of APIs built on StepZen providing data to frontends like React, Next, Nuxt and many more, see the StepZen Samples repositories.

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.