StepZen GraphQL API Workshop

Welcome! In this workshop, you'll learn how to create a GraphQL based on the most popular data sources (REST, MySQL, Postgres, GraphQL) with StepZen.

For this workshop, you can select different data sources from the Getting Started section below. These data sources can be run locally with Docker or Node.js and are prepopulated with data to get you started building GraphQL APIs with StepZen.

Getting Started:

You need to (globally) install the StepZen CLI, for which you need Node.js and NPM installed:

npm i -g stepzen

After installing the CLI, you can create a free account here or continue with a public GraphQL API endpoint.

If you want to start building a GraphQL on a MySQL or Postgres, make sure to read the requirements for these data sources. You must have Docker and ngrok installed on your machine.

Assignments

1. Choose one of the three prepopulated data sources we have prepared for you:

   • MySQL
   • Postgres

   Use the StepZen CLI to introspect the database and generate a GraphQL schema for it. You can start this GraphQL API using stepzen start.

   IMPORTANT: Do not select the option to create relation types. We will take this steps manually to understand better how it works.

   Solution:

   You can find the complete and working solution in the branch ex-1.

   • For MySQL

   stepzen import mysql

   • For Postgres

   stepzen import postgresql

2. Check the connection to your data source by running the query to get a list of orders and their customer and shipping cost.

   Solution:

   You can find the complete and working solution in the branch ex-2.

   query {
     getOrderList {
       customerId
       shippingCost
     }
   }

   Tip: Are you getting an error? Have a look at the GraphQL schema that is visible in GraphiQL. Check if the data source is configured correctly in config.yaml according to the READMEs for MySQL, Postgres or REST. If you've selected MySQL or Postgres as a data source, check if the tunnel with ngrok is running and the correct URL is added to config.yaml.

3. Next to importing the GraphQL schema, you can also use GraphQL SDL to create queries. Add a new query to get a customer by its id.

query {
  getCustomerById(id: 1) {
    id
    email
    name
  }
}

This query should return the customer with id equal to 1.

Solution:

You can find the complete and working solution in the branch ex-3.

• For MySQL

  getCustomerById(id: Int!): [Customer]
    @dbquery(
      type: "mysql"
      query: """
      select * from `customer` where `id` = ?
      """
      configuration: "mysql_config"
    )

• For Postgres

getCustomerById(id: Int!): [Customer]
  @dbquery(
    type: "postgresql"
    query: """
    select * from `customer` where `id` = $
    """
    configuration: "postgresql_config"
  )

4. With StepZen, you can use custom directives, like @materializer, to combine data retrieved by different queries. The schema for your selected data sources has queries to get customers and orders, which return the types Customer and Order. Connect the field customerId on type Order to Customer using the @materializer directive so that you can query the GraphQL API with the following operation:

  getOrderList {
    shippingCost
    customer {
      id
      email
      name
    }
  }

This query should return the list of orders, including its customer.

Solution:

You can find the complete and working solution in the branch ex-4.

Add the customer field to type Order in the GraphQL schema for either MySQL or Postgres or REST. The @materializer will be configured to use the getCustomerById query when the getOrderList query requests the customer field. If so, it will take the field customerId and pass it to the getCustomerById query as an argument.

type Order {
  carrier: String!
  createdAt: Date!
  customerId: Int!
  customer: [Customer]
    @materializer(
      query: "getCustomerById"
      arguments: [{ name: "id", field: "customerId" }]
    )
  id: Int!
  shippingCost: Float
  trackingId: String!
}

5. Let's connect another data source to the data you've explored in the first questions. In this workshop, you've worked with one of the prepopulated data sources given to you. But you can also combine them. For example, extend the data in the database with data from a REST API.

You can get the book meta data information from the Google Books REST API endpoint: https://developers.google.com/books/docs/v1/getting_started).

Tip: To get a book by its ISBN, you can use the following endpoint: https://www.googleapis.com/books/v1/volumes?q=isbn:9780385513753.

Tip: Types cannot be duplicated. If you (in example) want to combine MySQL with REST, you need to make sure that these are deleted from the other .graphql file they are present.

Solution:

stepzen import curl https://www.googleapis.com/books/v1/volumes?q=isbn:9780385513753

And connect to products using @materializer

6. Let's add pagination for the queries to get a list of products.

For MySQL: pagination For PostgreSQL pagination

Solution:

Support

Thanks for joining this workshop! If you're looking for additional support, please head over to our Discord or open an issue in this repository.