Write Schema in Code

Write Your Project Files Manually for Complete Customization

This document describes how to write your SDL ( .graphql) files if you choose to write all of your project files from scratch.

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.

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

  3. 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. If you'd like to follow along, you can get your own Cat API key at the Cat API website.

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. 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. Create 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.