
Posting on behalf of [Brian](https://twitter.com/remotesynth/), [Anthony](https://twitter.com/ajcwebdev/),  [Samuel](https://twitter.com/samuelgarretth/), [Lucia](https://twitter.com/CerchieLucia/), [Carlos](https://twitter.com/carloseberhardt/), [Anant](https://twitter.com/jhingran/), and the entire StepZen team.

---
Last week over 150 developers wrapped up a week of building and learning at the [Mintbean](https://mintbean.io/) + [StepZen](stepzen.com) [**QraphQL:Learn 'n' Hack Hackathon**](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333). In this post, we'll take a look at the projects (in alphabetical order) that our *Learn 'n' Hackers* built. You can access a demo for each project and the source code in GitHub via the links below.

We were truly inspired by everyone's energy and creativity. We know that everyone learned a lot about GraphQL. We learned a lot too and we had a blast. We are thrilled to keep working with you on the Mintbean Discord and over on the [StepZen Discord](https://discord.gg/9k2VdPn2FR)

## Bearometric Radio
![bearometric radio](/images/blog/hackathon-bearometric.png)

[The Bearometric Radio](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/6f13c553-b14b-4707-b981-e7eb2cd13a52) web app recommends music to listen to based on the weather. [Will Campbell](https://www.linkedin.com/in/williamkcampbell/) and
[Jay Cammarano](https://www.linkedin.com/in/jay-cammarano/) built their app around a weather-report GraphQL API and a couple of music-related APIs. The app has a React frontend (with a touch of vanilla JS).

## Get a Dog

![dogs API](/images/blog/hackathon-dogs-api.png)
[The Get a Dog](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) web app allows you to select a dog type and returns information and a picture of a dog. [Ethan Wright](https://www.linkedin.com/in/ethan-wright-91a75270/) uses a React frontend and queries a GraphQL API for the [thedogapi](https://www.thedogapi.com/) that he built on StepZen.

## Holidays
![holiday app](/images/blog/hackathon-holiday-app.png)

[The Holidays app](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) calls two REST APIs (calendarific.com and ip-api) combining the responses into a single GraphQL endpoint. The React client queries for data about this year's holidays as if it was queried from a single GraphQL API. [Erica Melo de Carvalho](https://www.linkedin.com/in/erica-melo-de-carvalho/) and [Aamir Bakhtiar](https://www.linkedin.com/in/aamir-bakhtiar-86b3551ba/).

## Eature
![eature app](/images/blog/hackathon-eature.png)

[Stephanie Hou](https://www.linkedin.com/in/houstephanie/?miniProfileUrn=urn%3Ali%3Afs_miniProfile%3AACoAABY8h1ABRwDdMadoTCA2e47E6m0k1R4zxQk) and 
[Michael Fuery](https://www.linkedin.com/in/michaelfuery/) give us [Eature](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/eab19d21-b59e-4e4a-8a0d-7143f1ce2d36) - an app that lets us visualize events recorded by NASA's Earth Observatory Natural Event Tracker (EONET). The team brought a good amount of data together from several APIs to create an informative yet simple UI.

## Kiki's Recipe
![Kiki's Recipes app](/images/blog/hackathon-kikis-recipes.png)

For the [Kiki's Recipe](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) project
[Danny Serrano](https://www.linkedin.com/in/serranodanny/),
[Marjorie Mejia](https://www.linkedin.com/in/marjorie-mejia/), and
[Natalie Rojas](https://www.linkedin.com/in/natalie-o-rojas/) used the following technologies – React, Bootstrap, Spoonacular API, Apollo Client, GraphQL, StepZen, Heroku (deployment) – to build an app that allows us to provide 10 ingredients, hit submit and viola! - we are returned some amazing recipes.

## Lunch Time

For the [Lunch Time](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) app, our developers,
[Kelsey Schroeder](https://www.linkedin.com/in/kelsey-m-schroeder/),
[Leslie Meng](https://www.linkedin.com/in/leslie-meng/), and
[Calvin Lowe](https://www.linkedin.com/in/calvin-lowe/) take a different angle on the food theme. By building a GraphQL endpoint on a couple of Google Sheets data sources, they allow us to determine how much we can afford to pay for lunch today.

## MLB Showdown

![MLB Showdown app](/images/blog/hackathon-mlb-showdown.png)

For the [MLB-Showdown-StepZen](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/63562e68-1a01-4621-9b26-d3b9f94997dc) app,
[John Ratanaprasatporn](https://www.linkedin.com/in/john-ratana-7aa24063/) took his love for the MLB-Showdown card game and re-created it digitally by building a GraphQL API on a REST backend. John used React, React Spring and StepZen in his project.

## React StepZen Comets (Fireballs)
![Fireballs app](/images/blog/hackathon-fireballs.png)

For the [React StepZen Comets](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/68941c26-2b12-42a9-8828-3df18772f226) project,
[David Griffin](https://www.linkedin.com/in/david-griffin-117b0045/) and [Dale Sakamoto](https://www.linkedin.com/in/dalesakamoto/) built a site to track meteors using NASA's JPL Fireballs API. They generate an array of Meteor objects. Users input a location, the app queries the Google Maps API and generates longitude and latitude coordinates. By comparing the coordinates to the array of meteors, the app finds the closest recent meteor strike and returns the meteors impact energy and velocity. In a clever visualization, the app shows us how the comet's speed compares to the fastest man and car.


## Rocket-X
![Rocket X app](/images/blog/hackathon-rocket-x.png)

For the [Rocket-X](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/6681028f-634d-4f5a-9d2e-0d46ecc183c0) app,
[Nara K](https://www.linkedin.com/in/hurricanenara/) and [Lauren Lee](https://www.linkedin.com/in/lauren-hyuna-lee/) created a GraphQL API in StepZen that combined data from two REST APIs, api.spacexdata.com/v4/rockets and api.spacexdata.com/v4/launches, to show us all the rocket launches. They bootstrapped the project with Create React App.


## Running Event Page Creator
![running event page creator](/images/blog/hackathon-running-event.png)

[Jesse Moore's](https://www.linkedin.com/in/jesse-moore-00804030/) [Running Event Page Creator](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/321818e0-b00a-4faf-afe7-b1cf2ab014c8) is a single-page app that dynamically creates event pages using data from multiple tables in an Airtable base. Using StepZen, Jesse combines multiple REST queries into one client-side GraphQL query. The app converts the race name into a readable URL slug, parses a user-provided gpx file route into an interactive map, and user-provided latitude and longitude points into respective markers.


## The Cartoon Character Quiz
![cartoon character quiz](/images/blog/hackathon-cartoon-quiz.png) 

Naomi C. built this [Cartoon Character Quiz](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/abe736f7-4bbf-4f87-b79c-f2447f8a3cd4) using StepZen, GraphQL, and the REST [Last Airbender API](https://github.com/paigeegorry/last-airbender-api). Give it a try - it's addictive!

## SpaceX Launch Dashboard
![SpaceX Dashboard](/images/blog/hackathon-spacex-dashboard.png)

[Seth Mitchell](https://www.linkedin.com/in/sethayottemitchell/) and Steven Larsen built a [SpaceX Launch Dashboard](https://github.com/sethayotte/SpaceX-Launch-Dashboard), .

> "We were able to build a comprehensive and dynamic launch dashboard utilizing SpaceX's API with minimal code using super-cool "materializers" to pare back and condense queries to only necessary response data.
![spacex app tweets](/images/blog/hackathon-spacex-tweets.png)


## The Pointless Dashboard
![The Pointless Dashboard](/images/blog/hackathon-pointless-dashboard.png)

[Nina Jhunjhnuwala](https://www.linkedin.com/in/ninajhunjhnuwala/),
[Jerry Ong](https://www.linkedin.com/in/jerryong89/), and
[Christopher Gitmed](https://www.linkedin.com/in/christopher-gitmed/) treat us to [The Pointless Dashboard](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f89b44e4-1687-4df3-a133-ac46a6de30d3). Well, they had a point! They determined the best way to learn GraphQL was to make the API and do a bunch of API queries. They used React.js and Bootstrap 4 on the frontend. Then StepZen to convert REST APIs into GraphQL endpoints. Then GraphQL to query the APIs and fetch the data necessary to populate the various widgets on the dashboard.

---
The [StepZen team](/about) looks forward to continuing our exploration of GraphQL with you all and can't wait to see what you build next. Hit us up anytime on the [StepZen Discord](https://discord.gg/9k2VdPn2FR).

Huge gratitude to to our friends at [Mintbean](https://mintbean.io/). We look forward to working with you all again. Not yet signed up for StepZen? [Try it free](https://stepzen.com/request-invite).

Along with the mintbean.io team, we wrapped a **GraphQL:Learn 'n Hack Hackathon** last week. Developers had a blast building with GraphQL and we loved working with everybody. Here are some of the projects that developers built.


GraphQL Hackathon: It's a Wrap


We are delighted to announce the launch of [StepZen API Templates](https://stepzen.com/developers/api-templates/) — the simplest and fastest way to build a GraphQL API that connects REST, SOAP, and GraphQL APIs, SQL and NoSQL databases, or any other backend data sources into a single unified  endpoint that developers can query to get the data they need.

API Templates are pre-made GraphQL schemas configured with schema types, queries, and connections to backend data sources. Browse the [API Templates Gallery](https://stepzen.com/developers/api-templates/)  or access them in the GitHub repository: https://github.com/steprz/stepzen-schemas. Starting with the StepZen CLI to import one or more templates from the [GitHub repository](https://github.com/steprz/stepzen-schemas), it takes only minutes to create a GraphQL API from a whole range of popular APIs. 

## Your GraphQL endpoint live in minutes

The `stepzen import` and `stepzen start ` CLI commands work together and let you first *import* a template from the repository, then upload and deploy the GraphQL API right away so that you work with a live endpoint as you extend and customize it. Here's Carlos to show us how:

<iframe width="460" height="380" src="https://www.youtube.com/embed/BoL-h1_Zp1o?rel=0" frameborder="10"  allowfullscreen></iframe>



## Building blocks simplify and speed GraphQL API development

Whether enabling static and dynamic interactions with APIs on Jamstack sites or building sites and apps with other web technology, today’s developer is connecting and orchestrating a complex network of data sources - from APIs to databases.  All have different interfaces, languages, protocols, and authentications; all have varying levels of good, bad, and ugly documentation for you to explore and hopefully learn how to connect and effectively work with the data. 

When it comes to fetching and consuming data, there are many reasons to believe in [GraphQL as the right technology](/blog/why-graphql) to simplify frontend and back-end developer workflows. API Templates are building blocks that give you a jumpstart on creating your GraphQL API. 

- You are productive in minutes. You don’t need to learn how to build a GraphQL server, understand resolvers, or the details of GraphQL stitching to build and deliver a GraphQL API that connects all the data you need into an easy-to-query graph.
- API Templates come pre-configured with connections to specific backend data sources. Some are open and can be used right away. For those that require keys or credentials, the `stepzen import` CLI prompts you to provide the relevant information. The CLI uses your responses to write the configuration file (config.yaml) , which securely saves the keys and other credentials that StepZen needs to access the backends. 
- StepZen is a managed service, meaning no infrastructure headaches for developers at runtime. Even at build-time, thanks to a built-in mock service, you use  the  `stepzen start` command to deploy and run your API as you design it, making iteration and testing easy.
- After you import a template, you have laid down your optimized project structure, and have a solid starting point to extend and customize the schema files, the specifications for backend connectors, the configurations, the linking of types, and more. 
- Each folder in the [GitHub repository](https://github.com/steprz/stepzen-schemas) is self-contained and provides the information about what's needed regarding authentication, keys, IDs, and so on for the data sources the template integrates. 
- You have the flexibility to mix and match schemas as needed depending on your domain and use case.  

## Where to go from here

We continue to add to our API templates ecosystem, and if there's one you'd like to have or an extension to an existing one, we'd [love to hear your ideas](mailto:feedback@stepzen.com). 

If you're already signed up for StepZen, there's nothing you need to do to start building with templates. Not yet signed up? Try it free here https://stepzen.com/request-invite. For documenation, check out the [GitHub repository](https://github.com/steprz/stepzen-schemas/blob/main/README.md) and the [StepZen docs](my.stepzen.com/docs/setup).  

We look forward to seeing what you build. 

A new library of API template schemas make it easy for developers to build a unified GraphQL API starting from a template. Save weeks of development time! No need to build a GraphQL server, understand resolvers, GraphQL stitching etc.


API Templates: How to Build a GraphQL API in 3 Easy Steps


At StepZen, we believe there's a lot of power in providing developers with a single, consolidated API that brings together all of their disparate backends. But we also want to make that power available to developers as quickly and easily as possible. That's why we've been focused on creating tools that can help make the process of getting started building your API in StepZen even easier. Today I wanted to share two new capabilities we just released - `create-stepzen-app` and `stepzen start`. The two features work together to simplify the process of building and deploying your GraphQL API on StepZen.

Let's see how this works!

## create-stepzen-app

`create-stepzen-app` is a new tool that generates starter code to help you get begin deploying, testing and customizing your first GraphQL API using StepZen. You can use `create-stepzen-app` via npx:

```bash
npx create-stepzen-app my-project
```



You'll be asked a series of questions (mostly just your account details, which are preset if you've already run `stepzen login` on the StepZen CLI). Finally, it will offer you the option to choose from pre-existing templates.
![running create-stepzen-app](/images/blog/run-create-stepzen-app.gif)

For example, choosing `hello-world` sets up a simple StepZen API to get the weather from OpenWeatherMap using longitude and latitude.

```graphql
interface WeatherReport {
    date: Date!
    latitude: Float!
    longitude: Float!
    temp: Float
    feelsLike: Float
    description: String
    units: String
}

type OpenWeatherMapReport implements WeatherReport {}

type Query {
    weatherReport (latitude: Float!, longitude: Float!): WeatherReport
    openWeatherMapReport (latitude: Float!, longitude: Float!): OpenWeatherMapReport
        @supplies (query: "weatherReport")
        @connector(type: "__openweathermap_weather_location_connector__", configuration: "owm_default")
}
```

If you change directory into `hello-world`, we can explore a new feature of the StepZen CLI.

## stepzen start

We are continuously improving the developer experience while building, deploying and testing an API on StepZen. To that end, `stepzen start` eliminates the need to run multiple commands to upload schemas and configurations and then deploy them. It also eliminates the need to have something like GraphQL Playground installed to test queries against your new API. Instead, everything is taken care of by `stepzen start` and you can test via the embedded GraphiQL editor.

Let's see how this works. If you've generated a project using `create-stepzen-app` it has the default project structure that `stepzen start` assumes (don't worry if you don't as you can override the defaults, just run `stepzen start --help` for a list of options). For instance, running `stepzen start api/hello-world`, where `api/hello-world` are my `folder/schma-name`, from within the `hello-world` project will automatically upload the API and configuration, deploy it and then open a GraphiQL browser editor to test it.

![running stepzen start](/images/blog/stepzen-start.gif)

The GraphiQL editor that opens in a browser tab is already connected to my new API deployed on StepZen. This means I can immediately run queries against it for testing.

![embedded GraphiQL](/images/blog/graphiql-embedded.png)

Even better - `stepzen start` now watches any changes I make to my files and then automatically uploads and deploys them, making the build/deploy/test workflow much faster and more convenient.
## Where to Go From Here

If you're already a part of the StepZen private alpha, all you need to do is update the CLI to get accesss to `stepzen start`. Just run `npm update -g stepzen` and you're good to go! Nothing additional is required to use `create-stepzen-app`.

If you're not already part of the private alpha, you can [request an invitation](https://www.stepzen.com/request-invite).

To learn more about how to use both `create-stepzen-app` and `stepzen start`, check [the docs](https://my.stepzen.com/docs/helloworld).


We've added two new capabilities that make it even easier to get started with StepZen — create-stepzen-app and stepzen start. Let's see how they work.


An Improved Getting Started Experience


One of the problems facing developers today is that we are getting data from a disparate variety of sources. One application may get data from a variety of internal RESTful APIs, internal databases and even third-party APIs and services. It is rare that all these pieces know about each other - even across internal APIs - so it falls upon the developer to write complex and often fragile code to bring all these systems together.

[StepZen](https://stepzen.com) offers a platform that solves these problems by enabling developers to bring all the pieces of their backend together into a single API enabled via GraphQL. Curious? In this tutorial, we'll walk through the steps to building your first GraphQL API using StepZen. In this case, we'll use a MySQL backend, but be aware that StepZen supports multiple backend connectors.

Before we can get started, the first thing you'll need to do, of course, is get access to the [StepZen private alpha](https://stepzen.com/request-invite). It is free to use and we'll work to get you access quickly. Once you have access, there is a ton of [documentation](https://my.stepzen.com/) available to learn how the system works, but we'll walk through the key steps here.

## What We'll Build

We're going to build a very simple GraphQL API with *critically important* data about Scooby Doo characters and episodes. A GraphQL API is based around types, and our API will consist of two types: character and episode. For the sake of example, these are very simple (as we'll see in a moment).

The actual data will come from a MySQL database. I am hosting my MySQL database via Heroku, but where you choose to host the database isn't important provided that it is accessible by StepZen's service (if you'd like to use Heroku, the steps to do this are available in [the StepZen documentation](https://my.stepzen.com/docs/reference/setup-stepzen#setupyourownmysql(optional))).

### Creating the Database

Let's create our MySQL data by creating the two very simple tables and populating them with a little bit of data.

```SQL
CREATE TABLE `characters` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(45) NOT NULL,
  `isMonster` tinyint(4) DEFAULT '0',
  `episodeID` int(11) DEFAULT NULL,
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

CREATE TABLE `episodes` (
  `id` int(11) NOT NULL,
  `name` varchar(45) NOT NULL,
  `originalAirDate` date NOT NULL,
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

INSERT INTO `characters` VALUES (1,'Scooby Doo',0,0),(2,'Daphne Blake',0,0),(3,'Shaggy Rogers',0,0),(4,'Fred Jones',0,0),(5,'Velma Dinkley',0,0),(6,'Black Knight',1,1),(7,'Ghost of Captain Cutler',1,2),(8,'Phantom',1,3),(9,'Miner Forty-Niner',1,4);

INSERT INTO `episodes` VALUES (1,'What a Night for a Knight','1969-09-13'),(2,'A Clue for Scooby Doo','1969-09-20'),(3,'Hassle in the Castle','1969-09-27'),(4,'Mine Your Own Business','1969-10-04');
```
Ok. Now that we have our data, we can move on to the fun part - building the API.

## Getting Set Up With StepZen

Once you have your private alpha account on StepZen, the first thing you'll want to do is install the StepZen CLI.

```bash
npm install -g stepzen
```

Next, we'll need to connect the CLI to your StepZen account. The details you need can be found on the [my account page](https://my.stepzen.com/account). You'll need both the account name and the admin key. Run the following, replacing `[account name]` with the account from your [my account page](https://my.stepzen.com/account).

```bash
stepzen login -a [account name]
```

You'll then be prompted to enter your admin key. Don't worry, you'll only have to do this once.

## Creating the API

Let's start by creating a new project folder for our Scooby Doo API.

```bash
mkdir scooby-api
cd scooby-api
```
Next, we'll create the files for our GraphQL types: Character and Episode. These are written using standard [GraphQL SDL (Schema Definition Language)](https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51) that StepZen uses these to generate your full GraphQL schema. Before I start writing code, there are some key concepts to understand when building your API with StepZen:

* The fields and their associated types are written as a GraphQL interface. This is done so that you can have multiple implementations of a type in cases where the data may be supplied by multiple different backends. For example, a shipping type that uses both a FedEx and a UPS data source.
* A type is a concrete implementation of an interface and is typically used to define how the the connection to a backend where data is retrieved.

There's more to it than that, which you can [read about in the docs](https://www.my.stepzen.com), but, for now, let's get to writing some code. First, let's create a file to define the interface and queries for our Character type in a file named `character.graphql`:

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}

type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
}
```
Our character type has four fields. We've also defined two queries. One will get a single character based upon an ID and the other will get a list of characters based upon whether that character is a monster or not. Let's create a similar file called `episode.graphql` for our Episode type:

```graphql
interface Episode {
  id: ID!
  name: String!
  originalAirDate: Date!
}
type Query {
  episode(id: ID!): Episode
}
```

In this case, we have just three fields and only a single query defined to get an episode by its ID.

### Tying The Schema Together

We need one more file in order to tie the different files in our schema together for StepZen: `index.graphql`. It lists all the files in the schema that StepZen will use to assemble the GraphQL API. In this case, we only have two - `character.graphql` and `episode.graphql` - so our `index.graphql` will look like the following:

```graphql
schema @sdl(files: ["character.graphql", "episode.graphql"]) {
  query: Query
}
```
We're ready to upload our schema to StepZen. From the command line, be sure you are in your project's root folder and run:

```bash
stepzen upload schema scoobyapi/schema --dir=.
```

This will push the code to StepZen and perform some validation on it. The `scoobyapi/schema` represents the folder name and schema name for this schema. I can use whatever I want here, but it is important to note that whetever value I place here will be needed in later commands (also note that the folders are scoped to your user account, so you don't need to worry about name conflicts with other users).  You can specify a different directory than the one you are in by changing the `--dir` flag.

You should get a resonse like the following:

```bash
Uploading...
Successfully uploaded the schema
```
Ok. Let's go ahead and deploy this to StepZen. You'll want to deploy this to the same folder (i.e. `scoobyapi`) as the schema, though you can name it whatever like (I used `scoobydoo`). Supply the schema folder and name from the upload (`scoobyapi/schema`).

```bash
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema
```

You should receive a response like the following, though your endpoint will be different:

```bash
Deploying...
Redeployment successful!
Your endpoint can be found at: https://biggs.stepzen.net/scoobyapi/scoobydoo/__graphql
```

Using a tool like [GraphQL Playground](https://github.com/graphql/graphql-playground), we can now inspect our API using the URL provided. Open GraphQL Playground and enter the URL. You'll need to click HTTP Headers and provide the API Key from your [my account page](https://my.stepzen.com/account) as an authorization header in the following format:

```json
{
    "Authorization": "Apikey MYAPIKEY"
}
```

Now, if you click on docs, you should see the types associated with your new API.

![API docs in GraphQL Playground](/images/blog/api-docs.png)

However, if you try to run a query like:

```graphql
{
  character(id:1) {
    name
  }
}
```

...you'll get a null response:

```json
{
  "data": {
    "character": null
  }
}
```

This is because we haven't told our API where to get the data from yet. Let's do that.

### Connecting Mock Data

Connecting our API to mock data is as simple as adding a custom `@mock` [GraphQL directive](https://graphql.org/learn/queries/#directives) to our interfaces. For example, here is our updated `character.graphql`:

```graphql
interface Character @mock {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}

type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
}
```

Let's also add the same `@mock` directive to our `episode.graphql` and then upload and deploy:

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema
```

Now if we run the same query from earlier, we'll get mock data in the result:

```json
{
  "data": {
    "character": {
      "name": "In vel mi sit amet augue congue elementum"
    }
  }
}
```

## Connecting MySQL

Ok, mock data is great - and easy - but let's populate our API with some real data!

### Creating a Configuration

The first step to connecting a custom backend is to create our own configuration set to supply to StepZen that contains the connection information needed to connect to the MySQL database. Create a file called `config.yaml` within your project directory. You'll need your MySQL database username, password, hostname and database name. Assuming you have all that information handy, create a MySQL configuration in the following format (replacing the values in the `dsn` for your connection information):

```yaml
configurationset:
  - configuration:
      name: MySQL_config
      dsn: username:password@tcp(hostname)/databasename
```

Next you'll need to upload this configuration to StepZen. The best practice would be to place it in the same folder as the schema. You can name it whatever you like (I named mine just `config`). Keep this folder and name handy though as you'll need them again when we deploy.

```bash
stepzen upload configurationset scoobyapi/config --file=./config.yaml
```

You should receive a response like the following:

```bash
Uploading...
Successfully uploaded the configurationset
```
Now that StepZen knows how to connect to our database, we can modify the types to implement that backend.

### Creating Concrete Types

First of all, let's remove the `@mock` directive from each type as we're now going to populate it with real data. Next, we need to implement each interface as a concrete type to connect the backend. We can do this in separate files, but our types are simple enough here that, to keep things easy, we'll just add this to the current `character.graphql` and `episode.graphql`.

Let's look at the Episode type first. First we need to create the concrete implementation. In this case,  though we can leave it empty as to will only contain the same fields contained within the interface. I've named mine `EpisodeBackend` but you can name it whatever you like.

```graphql
interface Episode {
  id: ID!
  name: String!
  originalAirDate: Date!
}
type EpisodeBackend implements Episode {}
type Query {
  episode(id: ID!): Episode
}
```
Now that we have the concrete implementation, we can implement the query and connect it to MySQL. Here's the full complete code

```graphql
interface Episode {
  id: ID!
  name: String!
  originalAirDate: Date!
}
type EpisodeBackend implements Episode {}
type Query {
  episode(id: ID!): Episode
  episodeFromBackend(id: ID!): EpisodeBackend
    @supplies(query: "episode")
    @dbquery(type: "mysql", table: "episodes", configuration: "MySQL_config")
}
```

Let's break down the query (`episodeFromBackend`) piece by piece so that it makes sense:

* `episodeFromBackend` will supply data to our `episode` query and, as such, has the same arguments as that query. However, the query returns an instance of `EpisodeBakend` (our concrete implementation) rather than `Episode`.
* The `@supplies` directive is what tells StepZen which query this will fulfill. In this case, we're specifying that this query is supplying data to the `episode` query (i.e. the query directly above it).
* The `@dbquery` directive tells StepZen that this query will be fulfilled by a database query. We're supplying a type of `mysql` in order to use the MySQL connectors in StepZen and telling it to use the table `episodes` and the configuration `MySQL_config` that we defined earlier in our configuration set. Since our table fields match the fields in our type, we don't need to supply anything else - StepZen is smart enough to figure out the proper query to construct to get the data.

Let's go ahead and upload and deploy these updates to our schema. Notice that our deploy command now specifies the configuration we uploaded earlier via the `--condigurationsets` flag.

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```

Let's go ahead and test this out by running a query in GraphQL Playground:

```graphql
{
  episode(id:1) {
    name
  }
}
```

This should return the real data we populated at the beginning of this tutorial:

```json
{
  "data": {
    "episode": {
      "name": "What a Night for a Knight"
    }
  }
}
```

Let's do the same for the Character type, leaving out implementing the `characters` query for now:

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}
type CharacterBackend implements Character {}
type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
  characterFromBackend(id: ID!): CharacterBackend
    @supplies(query: "character")
    @dbquery(type: "mysql", table: "characters", configuration: "MySQL_config")
}
```

Upload and deploy it:

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```

And finally, query it:

```graphql
{
  character(id:1) {
    name
  }
}
```

The result should be:

```json
{
  "data": {
    "character": {
      "name": "Scooby Doo"
    }
  }
}
```

### Specifying a Custom Query

Our `characters` query allows us to get an array of characters by passing the `isMonster` query parameter. We'll need to supply the actual SQL query to StepZen so that it knows how to get the values. To do this, we pass a `query` parameter to the `@dbquery` directive rather than a `table` parameter as in the prior example. The `?` in the query will be replaced by the value of `isMonster` being passed.

Let's take a look at our `character.graphql` with the finished `charactersFromBackend` query. This query supplies the `characters` query with data from MySQL:

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}
type CharacterBackend implements Character {}
type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
  characterFromBackend(id: ID!): CharacterBackend
    @supplies(query: "character")
    @dbquery(type: "mysql", table: "characters", configuration: "MySQL_config")
  charactersFromBackend(isMonster: Boolean!): [CharacterBackend]
    @supplies(query: "characters")
    @dbquery(
        type: "mysql",
        query: "SELECT * FROM characters WHERE isMonster = ?",
        configuration: "MySQL_config")
}
```
Now we can upload and deploy it:

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```
Then let's try querying it:

```graphql
{
  characters(isMonster:true) {
    name
  }
}
```

You should get the following response:

```json
{
  "data": {
    "characters": [
      {
        "name": "Black Knight"
      },
      {
        "name": "Ghost of Captain Cutler"
      },
      {
        "name": "Phantom"
      },
      {
        "name": "Miner Forty-Niner"
      }
    ]
  }
}
```
## Stitching Types Together

We have a schema with two types, character and episode, that pull real data from MySQL. However, they aren't tied together in any way. I cannot get the episode that a character was in right now without making two queries. This may be how it often works with REST-based APIs, but certainly not with GraphQL. Let's address that.

What we want is that when we get a character, it gives the associated episode that they appeared in. To do this, we're going to use another custom directive `@materializer`. Let's look at the finished `character.graphql`, then we'll cover the specifics of how it is configured. They key difference to notice below is the `episode` field within the `Character` interface.

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
  episode: Episode
    @materializer(
      query: "episode"
      arguments: [{ name: "id", field: "episodeID" }]
    )
}
type CharacterBackend implements Character {
  id: ID!
  name: String!
  isMonster: Boolean!
}
type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
  characterFromBackend(id: ID!): CharacterBackend
    @supplies(query: "character")
    @dbquery(type: "mysql", table: "characters", configuration: "MySQL_config")
  charactersFromBackend(isMonster: Boolean!): [CharacterBackend]
    @supplies(query: "characters")
    @dbquery(
      type: "mysql"
      table: "characters"
      query: "SELECT * FROM characters WHERE isMonster = ?"
      configuration: "MySQL_config"
    )
}
```
We've created an `episode` field on our character that returns an instance of the `Episode` type. It uses the `@materializer` to call the query `episode` on the Episode type that we defined within our `episode.graphql`. The `id` argument that the query is looking for will be populated with the `episodeID` from the character.

Let's upload and deploy it.

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```
And try querying it, asking for a list of characters who are monsters and the name of the episode that they appeared in:
```graphql
{
  characters(isMonster:true) {
    name
    episode {
      name
    }
  }
}
```
Let's see the result:
```json
{
  "data": {
    "characters": [
      {
        "episode": {
          "name": "What a Night for a Knight"
        },
        "name": "Black Knight"
      },
      {
        "episode": {
          "name": "A Clue for Scooby Doo"
        },
        "name": "Ghost of Captain Cutler"
      },
      {
        "episode": {
          "name": "Hassle in the Castle"
        },
        "name": "Phantom"
      },
      {
        "episode": {
          "name": "Mine Your Own Business"
        },
        "name": "Miner Forty-Niner"
      }
    ]
  }
}
```

## Where To Go From Here

What we've touched on here really only gives you a taste of the real capabilities of StepZen. Imagine you're getting some of your backend data from MySQL and others from various RESTful APIs. StepZen would allow you to tie all those pieces together into a single API much the same way we tied our character and episode data together. This offers you a way not only to GraphQL-enable your existing backend, but to tie together disparate pieces into a single API accessible at a single endpoint. I hope you'll take some time to explore StepZen further via [the documentation](https://my.stepzen.com/docs) and share your thoughts and feedback with us.


A step-by-step guide to building a custom GraphQL API using StepZen that connects to a real MySQL backend.


Building Your First GraphQL API Using StepZen


Take a look at Google Maps or Google Search.

![Map with marked route](/media/blog/map-with-marked-route.jpg)

You specify what you want, and Google delivers the answer. How? You don't know, and typically don’t care. The hard work is done by Google, and not you, the consumer. Google does not program each and every query that might get asked. Instead, it figures out at the time the query is submitted, the best way of answering it. Of course, it might cache popular queries.

Or take a look at a database query.

```sql
select product.id, product.title from products, category
where category.label = “kitchenware” and
product.categoryid = category.id
```

You specify what you want, and the database produces the right answer. How? You don't know, and typically don’t care. The hard work is done by the database, and not you, someone who wants the data.

This is the declarative world. A world in which the developer, the user, the consumer declares what they want, and the system assembles the right bits to satisfy it. It cannot possibly imagine all pieces of information that might be requested, and in all ways it can be requested. The execution logic has to be assembled when the request is made (query execution plan, caching excluded).

There is a different world--the procedural world. The developer anticipates what forms of requests will be made, and carefully programs her way through all of them. All of server side code (that you fullstack developers write), and all the JavaScript code (that you front-end developers write) uses procedural logic--full of if-then-else logic, error handling etc.

Neither is good nor bad, they are just different. As a developer, procedural code gives you more control. As a user, declarative code gives you more flexibility.

The world of APIs (where StepZen's cofounders spent a decade together), is procedurally built. What that means is that all the ways in which a user-developer of the API might request the data are programmed. You get APIs that do precisely what the API developer wants them to do. If some other way is needed, then either the API has to change, or a new API has to be built.

Let’s take an example. An e-commerce experience that requires the delivery status of all the open orders might be coded by calling an API:
`/deliveryStatus?email=”jane.doe@example.com”&status=”open”`

Furthermore, the API developer would have written some logic like:

> Fetch orders from customer system for “jane.doe@example.com”
>
> For each order:
> Fetch shipments from order system
>
> For each shipment
> Fetch delivery status from the carrier
> If undelivered, add to the return answer

Now imagine errors. What if the delivery system does not respond?
Now imagine changes. What if the frontend wants only those orders that are shipped by FedEx?
Now imagine multiple order systems. Which one should we get the information from?
Now imagine a completely different experience: “fetch price of products based on location.” OMG, the whole set of problems repeats themselves.

And the challenge here is not just complexity of the code in these. It is the time taken to code it (which means that the user experiences cannot be changed as quickly as the market demands). It is the brittleness of code. It is the creeping of concerns. It is the replication of business logic in multiple places. And for the frontend developer, it is another set of OpenAPI specs, opening up Postman, reading docs, seeing what parameter goes where. It's pain for the backend developer, pain for the frontend developer.

What if APIs could be built using declarative techniques? Like SQL, if there were one API that abstracts all the backends away and the frontend developer just asks for what she wants? Where the hard work of connecting the dots, of errors, of caching, of optimization, of scatter/gather etc. were all done by API middleware? What if the logic for execution just depends on the introspection of the backends--what they take as input, and what they produce as output?

This is what we are doing at StepZen. Our vision is **_One API for All Your Data._**

> Get the data you want.
> Using APIs built through configuration.
> And run zero infrastructure.

StepZen as a company is quite young. But Steprz (the StepZen team) are veterans, having built databases, API management systems, and run services in the cloud.

Obviously, our first steps will be just that--first steps. We believe in the power of GraphQL. So initially (perhaps always?) our APIs will be GraphQL APIs. We know backends have complexity. So initially we will give you a set of popular SaaS backends. We know the power of developers. So we will give you a set of connectors and schemas that you can stitch together, modify and add, creating your own "One API for All Your Data." And we will give you all of that, as a service. So that you have to run zero infrastructure.

We are just getting started, and we hope you will join us in our journey.


StepZen's CEO shares what inspired us to create StepZen and the complex problems we are working to solve for developers.


Why StepZen?


Software is magical. However, software doesn’t run in the ether (maybe because there is no ether - well, other than a pleasant-smelling colorless volatile liquid, not at all useful for running software :). Software needs real hardware to run on.

Early on at StepZen, we had a decision to make. Shall we build container deployed software that a developer could deploy on her infrastructure (or serverless), or do we provide StepZen-as-a-Service?

We decided on a SaaS model. That is why we say:

>Get the Data You Want.
>Using APIs Built Through Configuration.
>And Manage Zero Infrastructure.

The reasons for this choice are simple.

Our goal is to take away the friction between what the frontend developers want and what the backend data sources expose. Deploying infrastructure is a major friction that we would reintroduce if we were to follow a pure software model.

One of the reasons for the growth of APIs has been APIs-as-a-business-model. Stripe is a payments API. Twilio is a communications API. These are available as a service, which means the frontend developer doesn’t have to worry about payment or communications going down. Why should she now have to run the APIs that connect all of these together?

Getting things like retries, caching, protocol mediations, continuous improvements, auto-scaling, IP whitelisting, and so on right is extremely difficult to do as pure software.

Finally, our ability to innovate is much much higher in a SaaS model.

That said, our software is built on Kubernetes, so we can well imagine that we’d be available for on-premesis container deployments in the future. However, for now, just configure, and get an endpoint that is always on. That’s StepZen for you.




Two of StepZen's founders explore the benefits that made them decide to build StepZen using a Software as a Service (SaaS) model rather than a container model.
