Design a GraphQL Schema

Define your API and backend connections

Most of the work of creating a GraphQL API in StepZen is done by writing the Schema Definition Language (SDL) file. SDL files are text files, usually named {name}.graphql. In this section, we'll show you how to build your schema in one of two ways:

  • By Importing One or More API Templates, which create .graphql files, preconfigured with types and connections to backends that provide data for those types, in your project structure. This is the easiest way to get started. We do the design for you!
  • By Creating Schema Files by Writing Code using standard GraphQL schema directives and a few custom StepZen directives, which can modify the structure and behavior of a GraphQL schema in ways not possible using SDL syntax alone.

Create Schema Files by Importing API Templates

This is the easiest way to create your first GraphQL API (endpoint). All you'll need is to browse the API Templates Gallery, find a template with the functionality you need, log in to StepZen and run the stepzen import command.

Let's get started!

1. Import a Template to Start a Project from Scratch

Refer to the instructions in the quick start guide. In about five minutes, you'll have a GraphQL API endpoint up and running, and you'll be querying it in your GraphiQL browser.

2. Import a Template to Extend an Existing Project

If you already have a project folder and GraphQL API (perhaps one you created using the quick start instructions above - or the one you created doing the quick start tutorial), you can extend it by importing other template schemas using the StepZen CLI.

  1. Go to your project directory

    cd [myprojectfolder]
  2. Import one or more template schemas

    stepzen import schema,schema,schema...

    The StepZen CLI imports the schema(s) you specified, saves them in your project folder, and creates an index.graphql file at the root of your project structure to consolidate the individual schemas into one.

    Here's an example of myprojectfolder structure, after importing two schemas cloudinary and airtable

    🐒➔ tree
        .
        ├── index.graphql
        ├── stepzen.config.json
        ├── config.yaml
        └── cloudinary.graphql
        └── airtable.graphql
    • .graphql - Two SDL files - in this case inside their respective folders (cloudinary/cloudinary.graphql and airtable/airtable.graphql). These are the component schemas, which include the specifications for backend connectors.

    • index.graphql - in the root folder. This file tells StepZen how to assemble the various type definition files into a complete GraphQL schema. It includes a comma-separated list of .graphql files in your project folder that you want to roll up to build out your GraphQL API endpoint.

      In this example, the index.graphql file looks like this (where sdl is a custom StepZen directive that specifies to StepZen all the .graphql files you want to assemble into your unified GraphQL schema (note: relative paths))

      schema
        @sdl(
          files: [
            "cloudinary/cloudinary.graphql"
            "airtable/airtable.graphql"
          ]
        ) {
        query: Query
      }
    • config.yaml- This file contains the keys and other credential information that StepZen needs to access Cloudinary and Airtable. To learn about this file, see Keys and Credentials Configuration Reference.

    • stepzen.config.json - This file contains the endpoint you have chosen.

  3. Deploy and run your GraphQL endpoint

    stepzen start

When you run stepzen start, the StepZen CLI opens up a browser with GraphiQL query editor, in which you can query your new endpoint, which has been uploaded and deployed to StepZen.

Behind the scenes, GraphiQL is connected to your endpoint at https://{ACCOUNT}.stepzen.net/{folder/name}/__graphl.

Create Schema Files by Writing Code

You can write all of your project files from scratch if you prefer. This section describes how to write your SDL ( .graphql) files.

We recommend the following process: 1. Create a type that a front-end application will query. This could be a customer type, an order type, a ticket, whatever.

  1. Define a query on your type so that your type can be useful.

  2. Define which backend your query is connecting to to determine where you'll get your data.

If you want to run your endpoint live as you iterate it, you can do so by running stepzen start on the StepZen CLI.

StepZen CLI automatically deploys your assets as you create them to an endpoint on{youraccount}.stepzen.net, and to a proxy on your local machine (localhost:8000), so that you can experiment right from your laptop.

1. Create Your Type

Make a file for your type named {type}.graphql (where {type} is the name of the type being defined - for instance, the file below might be breed.graphql). In the brackets, you'll specify the properties you want on the type. You'll be connecting to a REST API, but you won't need to worry about filtering data since we're using GraphQL. Here's an example, where the fields are defined on the type Breed:

type Breed {
  temperament: String!
  origin: String!
}

2. Define Your Query

You'll need to define a query on your type, adding it in like so. In our example, the breed is queried by id:

type Breed {
  temperament: String!
  origin: String!
}

type Query {
  BreedFromRest(id: String!): Breed
    @rest(
      endpoint: "https://api.thecatapi.com/v1/breeds/search?q=$id"
      configuration: "cat_config"
      setters: [
        { field: "origin", path: "origin" }
        { field: "temperament", path: "temperament" }
      ]
    )
}

See the @rest connector? That holds the API endpoint, the configuration reference, and the setters, which determine the path. For more detail on connecting to a REST API, see our docs on connecting to a REST API.

3. Create your configuration file

You'll need a configuration file to tell StepZen how to connect to your deployed database. Make a file called config.yaml that contains:

configurationset:
  - configuration:
      name: cat_config
      Authorization: Apikey {{CAT_API_KEY_HERE}}

4. Tie the Schema Together

The index.graphql file tells StepZen how to assemble the various GraphQL files together into a single schema. In this case, we only have a single file that makes up our schema.

schema
  @sdl(files: [
    "breed.graphql",
  ])
{
  query: Query
}

If you'd like to follow along, you can get your own Cat API key at the Cat API website.

There you have it!

If you run stepzen start, you'll see a browser tab pop up with your StepZen graphiql query editor ready to go!

Create a type that connects to more than one backend

If you want to know how to create one type that connects to more than one backend, continue to Design a Schema with Interfaces, where you'll learn about creating a schema with interfaces and concrete types.

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.