
Typically I advise people to use a server-side request to query a GraphQL API. This is because you can hide your API key in the server-side code. However, most Jamstack applications require you to write client-side code, so you can't use a server-side request. When you're in this situation, you can set up a proxy server to reroute your API requests internally, hiding the request from the user. In this post, I'll show you how to hide your API key using a proxy server in React.

## Creating a Proxy Server

Suppose you have a React application using Apollo Client to query a GraphQL API, for example, a StepZen GraphQL API. The endpoint requires you to provide an API key as a header, and its implementation in React will look like this:

```js
const client = new ApolloClient({
  uri: 'https://YOUR_USERNAME.stepzen.net/api/YOUR_ENDPOINT/__graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: `apikey YOUR_API_KEY`,
  },
});
```

When you use this client in your React application to send requests to the GraphQL API, React will execute the request on the client side. This means that the request is visible from the network tab in the browser, and when you're building an application that external users use they will be able to see this API key.

Luckily, there are ways to prevent this. Either by rendering your React application on the server side or by setting up a proxy server. The library `http-proxy-middleware` is a great tool to use when you want to proxy requests to an API. It only takes a couple of lines of code to set up and use, and it's very flexible. You can use it to proxy requests to any API, not just StepZen. You can also use it to proxy requests to multiple APIs. 

The code block below shows how to use `http-proxy-middleware` to proxy requests to a StepZen GraphQL API. When you're for example using Create React App (read more [here](https://create-react-app.dev/docs/proxying-api-requests-in-development
)), the proxy server is set up in a file called `src/setProxy.js` in the root of your React application:

```js
const { createProxyMiddleware } = require('http-proxy-middleware');

module.exports = function (app) {
  app.use(
    '/api/YOUR_ENDPOINT/__graphql',
    createProxyMiddleware({
      target: 'https://YOUR_USERNAME.stepzen.net',
      changeOrigin: true,
      headers: {
        authorization: 'apikey YOUR_API_KEY',
      },
    }),
  );
};
```

Or, even better, you can use the `dotenv` package to store your API key in a `.env` file and use it in your proxy server. This way, you can keep your API key secret without worrying about it being exposed in your code. The package is already installed in the `create-react-app` template, so you don't need to install or import it yourself.

In an `.env` file, you can store your API key like this:

```js
STEPZEN_API_KEY=YOUR_API_KEY
```

And use it in `src/setupProxy.js`:

```js
authorization: `apikey ${process.ev.STEPZEN_API_KEY}`,
```

Now you can run your app locally (with `npm start`) to make the GraphQL API available at `http://localhost:3000/api/YOUR_ENDPOINT/__graphql`. When you request this endpoint, or the shorthand `api/YOUR_ENDPOINT/__graphql`, a request to `https://YOUR_USERNAME.stepzen.net/api/YOUR_ENDPOINT/__graphql` will be made by the proxy server. The proxy server will also add the `authorization` header to the request so that it won't be available to the user of your application.

When using Apollo Client, or a different way to make GraphQL requests, you can use the same proxy server to make requests to your StepZen API:

```js
const client = new ApolloClient({
  uri: '/api/YOUR_ENDPOINT/__graphql',
  cache: new InMemoryCache(),
});
```

This way, you can make requests to your StepZen API without exposing your API key to the user of your application.

## Usage with Next.js

This example demonstrated how to use  `http-proxy-middleware` with a Create React App, but there are more examples of integrating a proxy server with other frameworks and libraries. Such as with Next.js, one of the most popular React frameworks. 

For Next.js you would implement the proxy server an [API Route](https://nextjs.org/docs/api-routes/introduction) instead of `src/setupProxy.js`. This API Route would be named after the GraphQL endpoint you want to target. Suppose you want the proxy to run on `http://YOUR_APP_URL/api/YOUR_ENDPOINT/__graphql`. Then you would create a file called `api/YOUR_ENDPOINT/__graphql.js` and add the following code:

```js
import type { NextApiRequest, NextApiResponse } from 'next';
import { createProxyMiddleware } from 'http-proxy-middleware';

const proxyMiddleware = createProxyMiddleware({
  target: 'https://YOUR_USERNAME.stepzen.net',
  changeOrigin: true,
  headers: {
    authorization: 'apikey YOUR_API_KEY',
  }
});

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  proxyMiddleware(req, res, (result: unknown) => {
    if (result instanceof Error) {
      throw result;
    }
  });
}

export const config = {
  api: {
    externalResolver: true,
  },
};
```

Now you can run your app locally (with `npm run dev`), and it will use your proxy server to make requests to your StepZen API. Like the Create React App example, you can query the GraphQL API at `http://localhost:3000/api/YOUR_ENDPOINT/__graphql` (or shorthand `/api/YOUR_ENDPOINT/__graphql`), and the proxy server will port the request to `https://YOUR_USERNAME.stepzen.net/api/YOUR_ENDPOINT/__graphql` -- including the `authorization` header.

## What's next?

You can also deploy your app to Netlify or Vercel, and it will use the proxy server to make requests to your StepZen API. With this small proxy server, you no longer have to worry about potentially exposing your StepZen API Key to any of the users of your application. More examples are available in the [`http-proxy-middleware` documentation](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/servers.md).

We'd love to hear your feedback on this blog post and StepZen. Questions? Comments? Ping us on [Twitter](https://twitter.com/stepzen_dev) or join our [Discord community](https://discord.gg/9k2VdPn2FR) to get in touch. 


When you're writing client-side code to make API requests, you might need a Proxy Server to hide your API Credentials. Let's see how to do this for a React application that uses Apollo Client and StepZen.


Hiding Your API Credentials Client Side using a Proxy Server in React


## Learn How StepZen Works in this Episode of *Learn With Jason*

> *"If I've got a bunch of services and we need to make complex calls with these services, I don't want to necessarily maintain a bunch of custom resolvers when I could do just something like this and say, yeah -- slam this query into this query into this query. And all that turns into a great experience for the frontend devs and for the user and StepZen is gonna automate the caching etc."* ~Jason Lengstorf

A couple of weeks ago, StepZen's [Carlos Eberhardt](https://twitter.com/carloseberhardt) got together with [Jason Lengstorf](https://twitter.com/jlengstorf) on the [Learn with Jason](https://www.learnwithjason.dev/) show. Check out the recording here!

[![Turn Any Data Source into GraphQL With StepZen](/images/blog/youtube--n4Ackk0xMe8-c05b58ac6eb4c4700831b2b3070cd403.jpg)](https://www.youtube.com/watch?v=n4Ackk0xMe8 "Turn Any Data Source into GraphQL With StepZen")


In this lively, hands-on session, Jason and Carlos discussed their own experiences with GraphQL, the pros and cons of GraphQL for frontend and backend developers, and StepZen's configuration-driven approach to building a GraphQL API. The main event was an hour of live coding where Jason built a GraphQL API on StepZen. Check it out to see how they 
- combined multiple data from numerous different sources, including location, weather, and maps APIs
- put some of StepZen's custom GraphQL directives through their paces
    - **`@rest`** to connect a REST service to your GraphQL API,  
    - **`@sequence`** to execute multiple queries in a sequence, returning a single result, and 
    - **`@materializer`** to connect multiple GraphQL types
- discussed combining data from multiple backends both at build time **and at runtime**
   . . . and much more.


> *For 80% use cases, this removes the need to go and build resolvers. You can define the whole thing in one place. You have your SDL and you can
map things one to the other using these directives.*"


## Where to go From Here

Huge thanks Jason and Carlos for an entertaining and informative session. To learn more:

- [Connecting any REST API as data source for a GraphQL schema](https://stepzen.com/docs/features/connect-a-rest-service)
- [Connecting different backends to your GraphQL schema](https://stepzen.com/docs/connecting-backends)
- [Connecting multiple GraphQL types using the @materializer directive](https://stepzen.com/docs/features/linking-types)
- Sequencing a series of queries into a single result [using the @sequence directive](https://stepzen.com/docs/features/executing-queries-in-sequence)
- [StepZen samples repo](https://github.com/stepzen-dev)  
- Future episodes of Live with Jason live at [https://www.twitch.tv/jlengstorf]()



In a recent episode of "Learn With Jason", StepZen's Carlos Eberhardt and Netlify's Jason Lengstorf discussed the pros and cons of GraphQL for developers, and showed us how StepZen works to easily let you build a GraphQL API on a number of data sources!


Turn Any Data Source into GraphQL With StepZen: A Learn With Jason Episode


Every Jamstack site needs data – whether that data comes from external sources like a headless CMS or a database or from local sources like Markdown and data files. That's fundamental premise of a static site generator (SSG), to take this data and convert it into pre-rendered HTML, CSS and JavaScript.

However, accessing that data isn't always easy. In some cases, the SSG doesn't have a built in way to call external data at build time. This is the case for many "traditional" SSGs like Hugo and Jekyll. In other cases, you may have relatively easy access to make API calls, but combining data from multiple sources can prove complex. Perhaps a final case would be that you have data in external sources, but you prefer to store your content in local Markdown and data files.

Previously, I wrote about an [experimental solution](https://www.netlify.com/blog/2021/06/10/how-to-build-a-database-driven-jamstack-site/) to this problem of a lack of easy API access by manually writing a build script in Node.js that called the an API generated by StepZen and converted the data to local files. Because it used StepZen, it could connect to data from anywhere – MySQL or Postgres databases, REST APIs and more. Today I want to share a solution called [stepzen-content-pull](https://www.npmjs.com/package/@remotesynth/stepzen-content-pull) that I am working on that eliminates the need to manually write that script. Using this tool, you can supply queries to your StepZen GraphQL API that can be connected to any backend StepZen supports and convert that data to Markdown, YAML or JSON data files for your SSG (and it works with any SSG).

> Please note that this tool should be considered beta. I have successfully tested it against multiple schemas of my own, but I would appreciate any feedback on how to improve it to make it work for your schemas.

## How It Works

In order to convert the data into files, the tool requires a configuration file. Essentially what this file does is supply the queries that should be run and give details about how each should be converted to files. You can supply multiple queries, but each query should output to a single type (Markdown, YAML or JSON). Let's take a look at a quick example that replicates the example from my original article.

In the below configuration, I supply my StepZen account and endpoint details and then my array of queries has only a single query. This query returns content for a list of pages that I want to include as posts in my Jekyll blog. First, I supply the `query`, which I can just copy and paste from the GraphiQL editor provided by `stepzen start`.

Next, I tell it that I want to convert it to Markdown with a `.md` extension (the tool also supports outputting to `.markdown`). In this case, I am not supplying a file name, just the file extension. This is because we are returning multiple results that each need to be unique files. In order to give each a unique file name, we supply a `slug_field`, which should be a string field that can be converted to a slug (ex. changing "My First Blog Post" to `my-first-blog-post`). We also need to indicate which field contains the Markdown body. All fields other than the `body_field` will be included in the frontmatter of the post.

Finally, we need to supply what folder we should put the outputted files into (for Jekyll, `_posts` makes sense) and supply any `additional_frontmatter` that we want included. This allows you to specify things like `layout` that your SSG might require. It is worth noting that all of these fields with the exception of `additional_frontmatter` are required to covert multiple query results into unique Markdown file outputs.

```javascript
module.exports = {
  account_name: 'biggs',
  endpoint: '/netlify/pets-blog',
  queries: [
    {
      query: `{
            getPosts {
              title
              body
              published
              id
              categories {
                name
              }
            }
          }`,
      convert_to: '.md',
      slug_field: 'title',
      body_field: 'body',
      folder: '_posts',
      additional_frontmatter: {
        layout: 'post',
      },
    },
  ],
};
```

The only other thing that the `stepzen-content-pull` tool requires is your `STEPZEN_API_KEY` from your [StepZen dashboard](https://dashboard.stepzen.com/account). You can supply this via a `.env` file or via the `--apikey` flag.

With the configuration and API key set, just run...

```bash
npx @remotesynth/stepzen-content-pull
```

And the tool will output each result into unique Markdown files within the `_posts` directory.

For details on how to configure the tool to include multiple queries, output JSON/YAML or output single Markdown files from a query that produces a single result, check the [documentation](https://www.npmjs.com/package/@remotesynth/stepzen-content-pull).

## Integrating Into Your Build

Once you have a configuration and `STEPZEN_API_KEY` environment variable set, all you need to do to get this integrated into your build is to add it to your build command. For example, for a Jekyll site, you might run:

```bash
npx @remotesynth/stepzen-content-pull && jekyll build
```

This will pull the content to local files before the site is deployed. If you're on Netlify, you could even integrate the [StepZen Netlify Build Plugin](https://www.netlify.com/blog/2021/05/14/netlify-build-plugin-of-the-week-stepzen/) to have a build process that:

1. Builds and deploys your StepZen GraphQL API
2. Pulls content from the API as local files
3. Builds and deploys the site to Netlify's CDN

The best part is that all of this would exist within a single project structure and deployed simply by checking in changes to the git repository tied to your Netlify site.

## Try It Out (Keep In Mind It's Beta)

I'd love for you to give this a try and let me know what you think. This is just an initial release and the tool could definitely use some better error messaging and debugging issues with your config file (it is [open source](https://github.com/remotesynth/stepzen-content-pull) so you can contribute too if you like). If you run into issues or you have features you'd like to see added, let me know. Hopefully it helps you pull any data from anywhere into your Jamstack site!


We can leverage StepZen to pull data from a variety of data sources and convert that data into Markdown, YAML and JSON data files using the new `stepzen-content-pull` npm package.


Converting API and Database Data to File-based Data for Jamstack Sites


We recently sat down (had a Google Meeting 😉 ) with Eve Porcello, [author](https://www.oreilly.com/library/view/learning-graphql/9781492030706/) of O'Reilly's _Learning GraphQL_, co-creator of [Moon Highway](https://moonhighway.com/), educator, and all-around GraphQL expert. It was delightful to hear Eve's take on the state of GraphQL, and we know you'll enjoy it too.

----------

_Lucia: From your perspective as an educator in the GraphQL space, what kind of company or developer is adopting GraphQL right now?_

Eve: Early on it was a bunch of React developers who had heard about GraphQL at React meetings and conferences. That group of people became the first wave of GraphQL evangelists because those two technologies worked really nicely together and it felt like an easy win for React developers to have GraphQL as part of the stack. But now, with widespread adoption, people are really coming at GraphQL from all sorts of different angles. It was really relegated to the JavaScript space for a while, but now everybody can really benefit from GraphQL, so there are tools exploding in all different areas, bringing a ton of different people to the table. Because of where GraphQL fits in the stack, frontend developers need it, backend developers need it, anyone who really deals with data is now dealing with getting that data from a GraphQL API. So it's interesting how many people it touches.

_Lucia: Kind of like how many people REST touches._

Eve: Yes it's similar.

_Lucia: But in this case you can wrap a REST API in a GraphQL API and I'm not aware you can do the reverse._

Eve: That's a really funny idea! That makes me want to write a blog about that and see if I can pull that off. We'll talk about that at some other time.

_Lucia: So my next question is, are there any industries you see that are further along the curve in adopting it than others or are they kind of in the same place?_

Eve: I think it's more company-based. I think companies have either chosen to adopt it or not, and I'd say at big companies-- large, large enterprise companies, there's so many people involved in that migration that it takes a while. As I said before, there have usually been a couple people who are really stoked on GraphQL, but rolling it out to the whole organization is a bigger project. There's such a shift in how you design an API, how you think about data and things like that. So I haven't noticed certain industries as much as certain tech companies that have the budget to take on the R&D cycle, but I've seen a lot of smaller companies using it as well. It's kind of all over the place.

_Lucia: The first big companies that jump to my mind are GitHub and AirBnB, which are obviously all about different products._

Eve: Yeah! GitHub was the first to make it seem ok to go down that road. You'll see a company that's in a certain industry adopt it, and then other companies follow suit, like AirBnB did, then Expedia went really hard on GraphQL as well. It's funny how the competitive edge of GraphQL is showing up-- I'm interpreting the situation, of course, I don't know that that was the influence.

_Lucia: What sort of problem is being solved? What is that competitive advantage?_

Eve: I think that problem is just trying to figure out, in a world where we have data in so many different places, how to get it into different user interfaces in some type of way. There's a move from monoliths and microservices, and lots of people created thousands of services. Then everybody who started working at that company with thousands of services was like: "what is going on? I don't know how to access that data." So GraphQL infuses a nice layer of organization in between.

_Lucia: It's kind of a way of digging ourselves out of a hole we created for ourselves._

_I wanted to ask, I was reading [your book](https://www.oreilly.com/library/view/learning-graphql/9781492030706/) and I was super interested in this paragraph here:_

 >With GraphQL, the typical architecture involves a single endpoint. The single endpoint can act as a gateway and orchestrate several data sources, but the one endpoint still makes organization of data easier.
In this discussion of REST drawbacks, it's important to note that many organizations use GraphQL and REST together. Setting up a GraphQL endpoint that fetches data from REST endpoints is a perfectly valid way to use GraphQL. It can be a great way to incrementally adopt GraphQL at your organization. <sup>1</sup>

_So, incremental adoption is something I'm interested in, and the different patterns that are there. Can you expound on why that'd be a great way to adopt it, and what are the patterns that you see?_

Eve: That's probably one of the more common ones I think-- early on in the GraphQL story it was like "You have to get rid of REST, burn down your REST APIs", but Twitch is one of the first ones that comes to mind as one of the first to wrap their endpoints in GraphQL, and you can pick up a lot of speed from a performance perspective, because you can still cache data with your REST APIs but it means that you basically just write a schema and then fetch data from those REST endpoints, and then your frontend developers can write queries to get the data that they need. It basically 'protects' frontend developers from having to know the ins and outs of a bunch of different APIs-- they can just access all the data in one place.

_Lucia: Would you say that's decoupling the frontend and backend?_

Eve: Exactly. That's exactly what you can do. The frontend developers literally ask for what fields they want, and they don't have to worry about where the data is. It doesn't matter to them really-- they jsut want to make it show up. Similarly, the backend devs can jsut set it up so the resolvers fetch data from where it should be. Adding that extra layer is a nice division of duty for people.

_Lucia: So that's _how_ people adopt it. What do you think are the big struggles in the adoption of GraphQL?_

Eve: Organizational shifts and communication is a really big one. That gets overlooked when making a technology decision. Onboarding folks is really tough, because people think "GraphQL is really cool, and when people use it they'll feel like me." And I think people do feel like them eventually, but there may be some resistance at first. The sales story and the communications story about GraphQL can tend to be tricky because you're having to get so many people on board, and the shift from REST to GraphQL is not that daunting, however it _is_ a shift, so that's a big piece of it.

_Lucia: What are some things that make that shift easier?_

Eve: Companies that have done particularly well with this are creating internal working groups to spread the good word about GraphQL. They'll have training events, they'll have best practices, meetups internally just to communicate that this is what's going on, and that they're hoping to do this-and-that. That helps a lot. Just taking their time. We've talked about incremental adoption-- not trying to be like, we'll roll this out at the end of the month. Take more time and be more intentional about how that rollout goes and it'll yield better results.

_Lucia: So as far as you have incremental adoption, you'll have incremental communication mirroring it._

_Pivoting for now, what's your POV on the world of GraphQL in Jamstack?_

Eve: I think it makes a lot of sense there. It's always this story of taking everything apart, making it really small, then duct-taping it back together. GraphQL is the logical query language for that in that you can pull data from all these different data sources, all your different APIs, or your Cloud services that have your data, GraphQL really makes sense as a way of gathering all that together. GraphQL and Gatsby together, for example, people were like "What? This is wild. How are we doing this?" but it ended up being a really good decision because it makes sense to keep everything small, your requests small, and GraphQL helps facilitate that.

_Lucia: If you're in the philosophy of Jamstack, it's like "don't take on more than you need", and GraphQL is the epitome of that._

Eve: Totally.

_Lucia: Is there anything else you'd like to discuss?_

Eve: I think the GraphQL Foundation stuff is pretty interesting. There's a foundation now that gathers all these companies and vendors that use GraphQL. I think it will transform the way GraphQL works in the future. It's not just a Facebook thing, an Apollo thing, or a Prisma thing, instead it will be this community-based thing.

Another future thing is GraphQL Protocol. There's a blockchain implementation that uses GraphQL request. That will make sense too, because all these transactions take so long, and GraphQL makes sure that you request only the fields that you need, so it will speed things up. Ask Nader Dabit about that. It's a cool new area where GraphQL is going.

_Lucia: That's interesting-- I'd like to hear more about the foundation. I'd be fun to see a community where the main reason for it is a love of GraphQL._

Eve: The foundation kicked off in 2019 I think. It's responsible for managing the spec, the specification document that describes what's in the query language, the schema language, and all that stuff. That group of people decides what is in the language moving forward. It decides how GraphQL should have a community. GraphQL is fairly stable in that they try not to ship breaking changes. Instead, it's very additive, so they'll add cool things but not take them away. They're working on the defer and stream interfaces now. The defer and stream directives-- what that means, in short, is how to make queries faster. Instead of being like, "Hey give me all that data", and hanging out to wait for it, you get a stream of that data coming back, and you display certain fields, and other fields later.

_Lucia: I'm curious in terms of what's happening on the client and server ends when something is actively streaming._

Eve: It's basically, on the server side, there will be kind of a node.js interface for dealing with a file as a stream rather than a whole response. It really has to do with lists-- say you have a list of 100 books, you can specify how many books you want back initially, maybe 5, then it will stream you the rest in little chunks. Just like Netflix, right, when you don't download the whole movie, instead it'll just stream you little chunks of that. On the client it has to do with the query language. You'll say "Stream these fields" and the client will support those directives. It's more of a frontend developer tool for specifiying what information is most vital to display, then prioritizing that stuff. Then the libraries will take care of the rest. It will take a while to move into the spec, which is good, they're not throwing whatever they want in there, it's more of a formalized process.

----------

Thanks for sharing your time and your valuable perspective, Eve! So many great insights, and perhaps this is the simple truth about GraphQL in a world exploding with data:

>I think that problem is just trying to figure out, in a world where we have data in so many different places, how to get it into different user interfaces in some type of way.


An interview with Eve Porcello, who shares her view on the state of GraphQL and the JAMstack.


StepZen and Eve Porcello: A Conversation About GraphQL



***As we look ahead to [a joint Agility CMS and StepZen webinar ](https://agilitycms.com/resources/events/jamstack-graphql-headless-cms)to discuss how you can power up your Jamstack sites with GraphQL APIs and Headless CMS, we are thrilled to welcome Joel Varty to the StepZen blog to share his perspective on page management in Headless CMSs.***

One of the most important aspects of a content management system is how it gives non-developers the ability to edit content. I think we can all agree that, for the most part, we don't want our developers spending their time writing content (or copying and pasting it).
Most headless CMS stay away from "page management." They claim that the separation of content from its presentation disallows the management of "pages," as they are only intended for a single output - your website. While this is true, it also ignores the fact that the main anchor for online content is your website, and it needs a special case.
And yet creating pages, organizing sitemap, and re-ordering components on a page is one of the main tasks that editors often need help with when they work with a Headless CMS. However, it does not have to be this way.

## Let's Take a Step Back
When new customer experience channels (think Amazon Echo and digital signage) started to emerge, developers had a great idea.

“Let’s build a content management system that doesn’t care about which frontend you use. It just pulls and pushes content headlessly, to any channel or device using APIs!”

Suddenly, brands could write up content and design images to be spoken aloud by Amazon Alexa or displayed proudly on a wide-screen monitor at shopping malls, movie theaters and subway tunnels. The only problem was, those headless CMS solutions focus purely on the usage of APIs to push and pull content to external applications and channels - ignoring the needs of marketing teams to find, organize and create this content.

## What is Headless CMS?
[Headless CMSs](https://agilitycms.com/resources/guide/what-is-a-headless-cms) come in different forms. Some label themselves as API-first, some as content-first, and many other variations of the headless trend. However, there is a problem with the way headless CMSs operate.

Most of them can handle the storage and distribution of content that makes headless so attractive. These platforms recognize that it’s necessary to push content to various channels outside of standard websites. The ability to connect to APIs and distribute to any front end makes this possible. However, headless CMSs don’t cater to the ones producing this content - the editors and marketers.

Contrary to a traditional CMS, a headless content management system is entirely decoupled from the presentation layer or frontend, which is referred to as the "head." At the same time, the backend is your content repository and content management system, known as the "body."

When you separate your content repository "body" from its presentation layer "head," it becomes a headless CMS. However, what truly makes a headless CMS better than a traditional CMS is its content-first approach with full APIs to access and display content in any way desired.

![headless CMS](/images/blog/agility-headless-cms.png)

With this approach, a headless CMS enables you to author your content through the RESTful API and deliver that content wherever you need it — not just to a templated website or application.
A pure headless CMS doesn't generate any front-end code, which is why a headless CMS is sometimes referred to as "Content-as-a-Service" (CaaS).
This process results in the best available digital experience for the end-users of a particular device. Front-end developers can continue developing new functionality for any channel, independent of the core/backend CMS.

## Life Without Page Management
At the start of website development, a developer usually determines all the pages and routes in your site so that then they can build the content types to represent them.

But what about pages we want to add in the future? I'm not talking about merely adding new blog posts or articles here (those are list items, not pages), but instead adding actual new pages on the site, perhaps nested under other pages. What about landing pages, new lines of business, and so on? The second complication here comes when we've got many pages we want to create on our website. If we have to create a different content type to articulate that, we will have a ton of content types to define. Some CMS systems limit the number of content types, charging overages at a certain point. That's limiting in and of itself, but the bigger deal-breaker here is who is doing this work: Developers.

When we predefine our pages, a developer has to do the work of actually setting up those routes in code. Then they have to map those routes to the content types we defined earlier. Not only is that a great deal of work, but it means we have to get a developer involved again every time we want to add a new page!
There's a better way.
## What is Page Management?

A headless CMS acts primarily as a content repository, storing content for use on multiple channels. This isn’t enough for the modern-day marketer and limits the capabilities of the organization as a whole.
Most developers and architects start building their content using simple content definitions, and while that’s a good way to get started, it doesn’t scale well.

That’s why built-in page management is in high demand these days.
Page management empowers editors to create and manage content using reusable building blocks, also called modules. Using these building blocks, editors can manage their site’s page tree, edit SEO, and determine content relationships and the functionalities of each page. Also, developers can choose which modules editors can add, where they go, and what they do.
Page management also includes page templates. Developers create templates to narrow down the possibilities of what kind of content your website shows, giving the editors the tools to customize them but with a consistent output. Each page template has content zones that give editors a location to drag and drop modules.
## Why Headless CMS needs Page Management?

Let’s recap this one day in a life of a content editor from a typical marketing team:
- I need to create a new landing page specifically for the press. It will have the same content layout as the home page, but just different content.
- I need to set the SEO properties for each page, such as Meta Tags and Meta Descriptions.
- On the home page, we want the YoutTube video to be BELOW the Main Rich Text, but on our press page, we want the YouTube video to remain ABOVE the Main Rich Text.
- Our CEO doesn't like it - can we have the YouTube video ABOVE the Main Rich Text area on the homepage again?


In the scenarios above, you can see that the editor's needs are impossible to predict. It's not their fault. It's just the nature of the game. Managing content comes with a lot of changes.

Not taking advantage of Page Management for your digital solution means It's not flexible for editors. Hence, developers spend most of their time taking orders, tinkering with existing code to support content requirements, and wishing they were doing something else! Content changes should not have to involve developers.

So what does this ultimately mean?
- Editors cannot create/manage pages on their own without a developer
- Editors cannot control which components are on each page
- Developers get bored or burnt out
- More development resources/expenses required
- Productivity on the website suffers

And, who's at fault in this? I'll give you a hint, it's not the editor, and it's not the developer... It's the architecture!

## The Benefits of Headless CMS with Page Management
Using Page Management, you can empower editors to create and manage pages for your digital solutions using reusable building blocks (i.e., modules and page templates).
With page management, content editors can manage your site's page tree, page-level SEO properties, and determine what content and functionality will be on each page.
As a developer and architect, you still have full control over what page templates are available to the editor, where they can place modules within the page, and what the modules can do.
To sum up, the benefits of Page Management:
- Empowered editors who can do more without a developer
- Happier developers who can focus on new functionality and enhancements, and less time responding to new content requirements
- Increased productivity
- Fewer resources/expenses required

## Which Headless CMSs have Page Management?
According to [G2 Crowd Headless CMS grid](https://www.g2.com/categories/headless-cms#grid), there are three leaders in this space. Let’s review their Page Management options.

### Agility CMS
![Agility CMS](/images/blog/agility-best-both-worlds.png)

Agility CMS is the pioneer in this space. Agility had Page Management from the very beginning since 2003, it is not a recently added feature.
With Agility CMS, you can define three things that make Page creation and editing simple:

- **Page Templates**: Templates allow developers to determine a name and a set of modules where content editors can add content. Developers can also write code to render this template into an HTML document.
- **Modules**: Modules are reusable sets of fields that can go from a header to more complex UI elements such as a sliding image carousel. In short, modules are the building blocks that enable complex websites.
- **Digital Channels and Sitemaps**: A sitemap is a content structure that developers use to render the website. In Agility CMS, websites have one or more sitemaps defined, each in its own channel, enabling multi-site management and granular control over each digital property.
- **URL Management**: create redirects, test them, and do bulk edits right in the CMS
- **SEO Fields**: define meta keys words and meta descriptions, page names and decide if pages need to be shown in your sitemap right in the CMS.

The main thing about Agility CMS is that instead of coding and routing each page individually, developers now have to code only a few page templates and modules. These templates can be reused across the website, sharply reducing the amount of work that developers need to do from the beginning.


**The cost of Page Management with Agility CMS**

Page Management is included as a default feature on all Agility CMS pricing packages incl. a free Developer plan. It is FREE and you don’t need to pay extra to use it.
Agility CMS paid plans start at $490 for Business Pan.

### Contentful

![Contentful](/images/blog/agility-contentful-home-page.png)
[Compose](https://www.contentful.com/help/introduction-to-compose/) is a brand new application by Contentful that allows you to build and publish web pages in a few steps. Compose is a streamlined version of the Contentful web app designed specifically for editors and authors who don’t want to mess around with the more technical aspects of Contentful. Unlike the web app, Compose does not require content modeling knowledge. Instead, editors can assemble pages from predefined content components and media, without involving additional engineering resources.

Compose experience is not the same as using Contentful with Page Management and characterized by the following:
- Compose is used for the quick creation of web pages.
- Pages and fields are predefined and do not require extra setup.
- The hierarchy of the page building blocks is displayed in a single editing view.
- Entries can be published all at once with a single click.


**The cost of Page Management with Contentful**

For Team users, Compose + Launch can be added to all spaces within your organization for $1,995/month. The apps are available for a free 10 day trial, which will create a test space that allows you to test Compose + Launch without impacting the content or operations of your normal spaces.
Contentful Team plans starts at $499.
### Kentico Kontent

![Kentico Kontent](/images/blog/agility-kentiko-home-page.png)

Recently, Kontent offers Web Spotlight as their Page Management feature.
Web Spotlight combines in-context website management with the flexibility and multi-channel support of a headless CMS.

[Web Spotlight](https://docs.kontent.ai/tutorials/set-up-kontent/set-up-your-project/web-spotlight) makes it easy to create pages, add content, and rearrange components without any help from developers. Once you’re done, add the page to your navigation so all visitors can find it. With this feature, you can update content right within the pages of your websites. Changes can be made in seconds, without wondering how everything will look once it's published.

**The cost of Page Management with Kentico Kontent**

Web Spotlight is not included for free, you can add to your plan for $499/month. Kentico Plans start at $1249 for Business and $2,499 for Premium.


## To Wrap Up


Headless CMS is the future of content management and the movement away from Traditional CMS towards Jamstack API-based architecture is obvious.
Headless CMS is not just for developers anymore.
But enterprise teams with marketing professionals need the Headless CMS solutions that can empower content creators and free up developers time.
This is where Page Management comes in. With the help of page management, content editors can create and move pages around the sitemap in any way they see fit, adding modules to the websites and updating the properties of these modules as well.


All three Headless CMS leaders - Agility CMS, Contenful and Kentiko Content offer Page Management. Agility CMS offers it as a built-in feature for all plans including free. Contentful and Kentico charge $499 a month for a Page Management add-on.


## Where to go from here

Headless Content Management Systems are a core part of the modern eCommerce stack. Please join us for the joint Agility CMS and StepZen workshop - [Power up your Jamstack sites with GraphQL and Headless CMS](https://agilitycms.com/resources/events/jamstack-graphql-headless-cms) to discover how [StepZen](https://stepzen.com) can tie [Agility CMS](https://agilitycms.com/) data with eCommerce data from Shopify.


As we look ahead to [a joint Agility CMS and StepZen webinar ](https://agilitycms.com/resources/events/jamstack-graphql-headless-cms)to discuss how you can power up your Jamstack sites with GraphQL APIs and Headless CMS, we are thrilled to welcome Joel Varty to the StepZen blog to share his perspective on page management in Headless CMSs.


Why Headless CMS Needs Page Management


The RedwoodJS [Example Todo](https://github.com/redwoodjs/example-todo) is one of two canonical RedwoodJS applications, the another being the RedwoodJS [Example Blog](https://github.com/redwoodjs/example-blog). Both of these applications use Prisma Client to connect to a PostgreSQL database.

However, we can easily swap out Prisma and connect to another database such as [Neo4j](https://community.redwoodjs.com/t/using-redwood-with-neo4j-database/282) or [Fauna](https://css-tricks.com/deploying-a-serverless-jamstack-site-with-redwoodjs-fauna-and-vercel/) via a GraphQL endpoint.

This article describes another option - how to use [StepZen](http://stepzen.com) to swap in Airtable for the database in the [Example Todo](https://github.com/redwoodjs/example-todo) app.

## Setup

### Clone Example Todo repo

```bash
git clone https://github.com/redwoodjs/example-todo.git
```

### Install dependencies and start development server

```bash
cd example-todo
yarn
yarn rw prisma migrate dev
yarn rw dev
```

This will open a browser to `localhost:8910`.

![Redwood Example Todo on Localhost 8910 with Prisma](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ramfa10x65j0ac7mox0r.png)

## RedwoodJS Architecture

### Beginning Project Structure

A Redwood application is split into two parts: a frontend and a backend. This is represented as two node projects within a single monorepo. The frontend project is called `web` and the backend project is called `api`. These are referred to as "sides", i.e. the "web side" and the "api side".

```
├── api
│   ├── src
│   │   ├── functions
│   │   │   └── graphql.js
│   │   ├── graphql
│   │   │   └── todos.sdl.js
│   │   ├── lib
│   │   │   └── db.js
│   │   └── services
│   │       └── todos
│   │           └── todos.js
│   └── db
│       ├── migrations
│       └── schema.prisma
└── web
    ├── public
    │   └── favicon.png
    └── src
        ├── components
        │   ├── AddTodo
        │   │   └── AddTodo.js
        │   ├── AddTodoControl
        │   │   └── AddTodoControl.js
        │   ├── Check
        │   │   └── Check.js
        │   ├── TodoItem
        │   │   └── TodoItem.js
        │   └── TodoListCell
        │       └── TodoListCell.js
        ├── pages
        │   ├── FatalErrorPage
        │   │   └── FatalErrorPage.js
        │   ├── HomePage
        │   │   └── HomePage.js
        │   └── NotFoundPage
        │       └── NotFoundPage.js
        ├── App.js
        ├── Routes.js
        ├── index.css
        └── index.html
```

They are separate projects because code on the `web` side will end up running in the user's browser while code on the `api` side will run on a server somewhere.

- The `api` side is an implementation of a GraphQL API. Your business logic is organized into "services" that represent their own internal API and can be called both from external GraphQL requests and other internal services.
- The `web` side is built with React and includes a router that maps URL paths to React "Page" components. Cells allow you to declaratively manage the lifecycle of a component that fetches and displays data.

## Redwood API Side

### Change `id` type in `todos.sdl.js`

Our `schema` is contained in the `todos.sdl.js` file. We only have to make a slight change to the schema definition language.

```javascript
// api/src/graphql/todos.sdl.js

export const schema = gql`
  type Todo {
    id: Int!
    body: String!
    status: String!
  }

  type Query {
    todos: [Todo]
  }

  type Mutation {
    createTodo(body: String!): Todo
    updateTodoStatus(id: Int!, status: String!): Todo
    renameTodo(id: Int!, body: String!): Todo
  }
`
```

For each of the three instances of `id`, replace `Int` with `ID`.

```javascript
// api/src/graphql/todos.sdl.js

export const schema = gql`
  type Todo {
    id: ID!
    body: String!
    status: String!
  }

  type Query {
    todos: [Todo]
  }

  type Mutation {
    createTodo(body: String!): Todo
    updateTodoStatus(id: ID!, status: String!): Todo
    renameTodo(id: ID!, body: String!): Todo
  }
`
```

### Replace `PrismaClient` with `node-fetch`

If we look at our `db.js` file in `api/src/lib` we will see that we are importing `PrismaClient` from `@prisma/client` and initializing a `db` variable with `PrismaClient()`.

```javascript
// api/src/lib/db.js

import { PrismaClient } from '@prisma/client'

export const db = new PrismaClient()
```

Instead of using PrismaClient, we will install `node-fetch` so we can make `fetch` requests from the Redwood API as described in the [Using a Third Party API](https://redwoodjs.com/cookbook/using-a-third-party-api) cookbook.

```bash
yarn workspace api add node-fetch
```

We no longer need our `db` folder containing our Prisma migrations.

```bash
rm -rf api/db
```

We'll also rename the file to `stepzen.js`:

```bash
mv api/src/lib/db.js api/src/lib/stepzen.js
```

Delete all the code in the newly named `stepzen.js` file and replace it with the following:

```javascript
// api/src/lib/stepzen.js

const fetch = require('node-fetch')

async function client(data) {
  const response = await fetch(process.env.API_ENDPOINT, {
    method: 'POST',
    body: data,
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Apikey ' + process.env.API_KEY,
    },
  })

  const r = await response.json()
  return r
}

async function todos() {
  const TODOS = JSON.stringify({
    query: `query Todos {
      todos {
        body
        id
        status
      }
    }`,
  })

  const res = await client(TODOS)
  return res.data.todos
}

async function createTodo(input) {
  const CREATE_TODO = JSON.stringify({
    query: `mutation CreateTodo {
      createTodo(body: "${input.data.body}") {
        id
        body
        status
      }
    }`,
  })

  const res = await client(CREATE_TODO)
  return res.data.createTodo
}

async function updateTodo(input) {
  if (input.data.status !== undefined) {
    const UPDATE_TODO_STATUS = JSON.stringify({
      query: `mutation UpdateTodo {
        updateTodoStatus(id: "${input.where.id}", status: "${input.data.status}") {
          body
          id
          status
        }
      }`,
    })

    const res = await client(UPDATE_TODO_STATUS)
    return res.data.updateTodoStatus
  }

  if (input.data.body !== undefined) {
    const RENAME_TODO = JSON.stringify({
      query: `mutation RenameTodo {
        renameTodo(body: "${input.data.body}", id: "${input.where.id}") {
          body
          id
          status
        }
      }`,
    })

    const res = await client(RENAME_TODO)
    return res.data.renameTodo
  }
}
```

Lastly, we export an `sz` object with the functions we need to import into our services: `findMany`, `create`, and `update`.

```javascript
// api/src/lib/stepzen.js

export const sz = {
  todo: {
    findMany: () => {
      return getTodos()
    },
    create: (input) => {
      return createTodo(input)
    },
    update: (input) => {
      return updateTodo(input)
    },
  },
}
```

### Replace `db` with `sz` in `todos.js` service

Redwood automatically connects your internal services with your frontend GraphQL client, reducing the amount of boilerplate you have to write. Your services can interact with a database via Prisma Client, or they can be written for any other backend database technology.

Redwood automatically imports and maps resolvers from the corresponding services file onto your SDL. These files are contained in the `api/src/services` directory. This lets you write those resolvers in a way that makes them easy to call as regular functions from other resolvers or services.

If we look at the current `todos.js` file for the Example Todo app we see that it imports `db`, which was initialized with the Prisma Client.

```javascript
// api/src/services/todos/todos.js

import { db } from 'src/lib/db'

export const todos = () => db.todo.findMany()

export const createTodo = ({ body }) => db.todo.create({ data: { body } })

export const updateTodoStatus = ({ id, status }) =>
  db.todo.update({
    data: { status },
    where: { id },
  })

export const renameTodo = ({ id, body }) =>
  db.todo.update({
    data: { body },
    where: { id },
  })
```

We simply replace `db` with the `sz` object we created earlier.

```javascript
// api/src/services/todos/todos.js

import { sz } from 'src/lib/stepzen'

export const todos = () => sz.todo.findMany()

export const createTodo = ({ body }) => sz.todo.create({ data: { body } })

export const updateTodoStatus = ({ id, status }) =>
  sz.todo.update({
    data: { status },
    where: { id },
  })

export const renameTodo = ({ id, body }) =>
  sz.todo.update({
    data: { body },
    where: { id },
  })
```

## Redwood Web Side

### Change `id` type in `TodoListCell.js`

On the `web` side we have to make the same change in `TodoListCell.js`.

We make the same change to our types that we made to our `schema` on the `api` side by changing `Int` to `ID` for the `id` type.

```javascript
// web/src/components/TodoListCell/TodoListCell.js

const UPDATE_TODO_STATUS = gql`
  mutation TodoListCell_CheckTodo($id: ID!, $status: String!) {
    updateTodoStatus(id: $id, status: $status) {
      id
      __typename
      status
    }
  }
`
```

That's all it takes to completely rewire your Redwood project! But how is it connecting to Airtable? That's the magic of StepZen. We have a schema that allows us to directly query our REST endpoints from Airtable.

## StepZen Side

A StepZen project contains the following files:

- `index.graphql` tells StepZen how to assemble the various type definition files into a complete GraphQL schema.
- One or more GraphQL Schema Definition Language (SDL) files ending in `.graphql`.
- `config.yaml` contains the keys and other credential information that StepZen needs to access your backend data sources.

To setup our StepZen API, let's create a `stepzen` directory within our Redwood project's API folder. Within the `stepzen` folder, create a `schema` directory.

```bash
mkdir api/stepzen api/stepzen/schema
```

Every StepZen project requires an `index.graphql` that ties together all of our schemas. Create an `index.graphql` file for our `schema` and a `todos.graphql` file for our `Todo` type, `Query` type, and `Mutation` type.

```bash
touch api/stepzen/schema/todos.graphql api/stepzen/index.graphql
```

### `todos.graphql`

Let's create a `Todo` GraphQL type that represents a todo being returned by the Airtable API. `todos.graphql` has a `Todo` type and a `todos` query that returns an array of `Todo` objects. Our `Todo` type has only a few properties.

```graphql
# api/stepzen/schema/todos.graphql

type Todo {
  id: ID!
  body: String!
  status: String!
}
```

Our `todos` query is connected to the Airtable REST API using StepZen's custom `@rest` directive. The `@rest` directive accepts the URL of the REST `endpoint` that we want to connect.

```graphql
# api/stepzen/schema/todos.graphql

type Query {
  todos: [Todo]
    @rest(
      resultroot: "records[]"
      setters: [
        { field: "body", path: "fields.Todo" }
        { field: "status", path: "fields.Status" }
      ]
      endpoint: "https://api.airtable.com/v0/$baseid/todos/"
      configuration: "myAirtable"
    )
}
```

We will also need mutations for `createTodo`, `updateTodoStatus`, and `renameTodo`.

```graphql
# api/stepzen/schema/todos.graphql

type Mutation {
  createTodo(body: String!, status: String! = "off"): Todo
    @rest(
      resultroot: "records[]"
      setters: [
        { field: "body", path: "fields.Todo" }
        { field: "status", path: "fields.Status" }
      ]
      endpoint: "https://mutate-airtable-zlwadjbovq-uc.a.run.app/POST/$baseid/todos?Todo=$body;&Status=$status;"
      configuration: "myAirtable"
    )

  updateTodoStatus(id: ID!, status: String!): Todo
    @rest(
      resultroot: "records[]"
      setters: [
        { field: "body", path: "fields.Todo" }
        { field: "status", path: "fields.Status" }
      ]
      endpoint: "https://mutate-airtable-zlwadjbovq-uc.a.run.app/PATCH/$baseid/todos?Status=$status;&id=$id;"
      configuration: "myAirtable"
    )

  renameTodo(id: ID!, body: String!): Todo
    @rest(
      resultroot: "records[]"
      setters: [
        { field: "body", path: "fields.Todo" }
        { field: "status", path: "fields.Status" }
      ]
      endpoint: "https://mutate-airtable-zlwadjbovq-uc.a.run.app/PATCH/$baseid/todos?Todo=$body;&id=$id;"
      configuration: "myAirtable"
    )
}
```

### `index.graphql`

Our `schema` in `index.graphql` ties together all of our other schema files. For this example, we have only one - the `todos.graphql` file, which is included in our `@sdl` directive.

```graphql
# api/stepzen/index.graphql

schema @sdl(files: ["schema/todos.graphql"]) {
  query: Query
}
```

The `index.graphql` tells StepZen how to assemble the various type definition files into a complete GraphQL schema. The `@sdl` directive is a StepZen directive that specifies the list of files to assemble. It includes a comma-separated list of `.graphql` files in your project folder.

### `config.yaml`

The `config.yaml` contains various configurations that can include the keys and other credential information that StepZen needs to access your backend data sources.

```bash
touch api/stepzen/config.yaml
```

WARNING! This file should be added to `.gitignore` as it likely contains secret information.

```bash
.idea
.DS_Store
.env
.netlify
.redwood
dev.db
dist
dist-babel
node_modules
yarn-error.log
web/public/mockServiceWorker.js
config.yaml
```

To connect an Airtable account, we need to supply our `baseid`, `tablename`, and `authorization` header.

```yaml
configurationset:
  - configuration:
      name: myAirtable
      baseid: <YOUR_BASEID_TOKEN>
      tablename: todos
      authorization: Bearer <YOUR_BEARER_TOKEN>
```

You can get this information in your Airtable account.

## Deploy Our StepZen Endpoint

Now that our schema has been created, we can use the StepZen CLI to deploy it. If you have not already installed and configured the StepZen CLI, you can follow the [instructions here](http://stepzen.com/docs/quick-start#install-the-stepzen-cli).

```bash
stepzen start
```

This command uploads and deploys your endpoint automatically. You are asked a few questions to configure your endpoint.

### 1. Name your endpoint

First, you are prompted to name your endpoint destination.

```
? What would you like your endpoint to be called? api/todos
```

### 2. Specify root directory

The CLI detects your `stepzen` directory.

```
? We have detected a schema in this directory. Set the schema root to "api/stepzen"? (Y/n) Y
```

This creates a file called `stepzen.config.json`.

```json
{
  "endpoint": "api/todos",
  "root": "api/stepzen"
}
```

This also deploys the schema to StepZen and lets you explore the endpoint from the StepZen dashboard. It also watches the directory for changes so that any changes that you make to your schema code is automatically uploaded and redeployed.

### 3. Create `.env` file and restart the development server

Create the `.env` file in your Redwood project to hold your StepZen API key and endpoint URL.

```bash
touch .env
```

```bash
API_ENDPOINT=<YOUR_API_ENDPOINT>
API_KEY=<YOUR_API_KEY>
```

Restart your development server so Redwood can inject the environment variables and return to `localhost:8910`.

![Redwood Example Todo on Localhost 8910 connected to Airtable](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/681tt3ed47er2r0vaa8u.png)

## Final Project Structure

```
├── api
│   ├── src
│   │   ├── functions
│   │   │   └── graphql.js
│   │   ├── graphql
│   │   │   └── todos.sdl.js
│   │   ├── lib
│   │   │   └── stepzen.js
│   │   └── services
│   │       └── todos
│   │           └── todos.js
│   └── stepzen
│       ├── config.yaml
│       ├── index.graphql
│       ├── stepzen.config.json
│       └── todos
│           └── todos.graphql
└── web
    ├── public
    │   └── favicon.png
    └── src
        ├── components
        │   ├── AddTodo
        │   │   └── AddTodo.js
        │   ├── AddTodoControl
        │   │   └── AddTodoControl.js
        │   ├── Check
        │   │   └── Check.js
        │   ├── TodoItem
        │   │   └── TodoItem.js
        │   └── TodoListCell
        │       └── TodoListCell.js
        ├── pages
        │   ├── FatalErrorPage
        │   │   └── FatalErrorPage.js
        │   ├── HomePage
        │   │   └── HomePage.js
        │   └── NotFoundPage
        │       └── NotFoundPage.js
        ├── App.js
        ├── Routes.js
        ├── index.css
        └── index.html
```

## Where to go from here

To learn more about StepZen and how to build a schema, visit the [StepZen docs](https://stepzen.com/docs). To learn more about how to configure Redwood and build the frontend, visit the [Redwood docs](https://redwoodjs.com/docs/introduction).

You can find more example repositories at the [StepZen Github](http://github.com/stepzen-dev). If you're not already signed up for StepZen, you can sign up [here](https://www.stepzen.com/signup).


The RedwoodJS Example Todo is one of two canonical RedwoodJS applications, each of which use Prisma Client to connect to a PostgreSQL database. However, we can easily swap out Prisma and connect to another database. This article describes another option - how to use StepZen to swap in Airtable for the database in the Example Todo app.


Build the RedwoodJS Example Todo App with Airtable as Backend


## StepZen Netlify Build Plugin

We’re thrilled to announce that, with a new Netlify build plugin, you can now easily deploy a GraphQL endpoint built on StepZen with your Netlify build. With this, you can keep your APIs and your website consistent, and test and release them together using your existing deployment and testing processes. You can find the StepZen build plugin in the [Netlify Plugin Catalog](https://app.netlify.com/plugins).

![Netlify Plugin](/images/blog/netlify-plugin.png)

    Plugin: StepZen
    Deploy a unified GraphQL endpoint in your Netlify Builds via StepZen

You are building your Jamstack sites and apps to serve up static and dynamic data using any number of APIs and data from myriad backends. However, APIs and backends have different authorizations, response protocols, syntax, and more. StepZen enables you to build a GraphQL API that is an **_API of APIs_** - different backends and ways of connecting to them are made uniform in the context of your GraphQL API. The unified API is easy to set up. You don't need to be a GraphQL expert, build a GraphQL server, or understand resolvers. You connect your API and database backends through configuration, not code. And, with a single query, you can ask for exactly the data you need to power your web experiences.

The StepZen plugin lets you easily integrate the deployment of the API in a Netlify build. No change is needed to the Netlify deployment process. Your GraphQL API runs on StepZen, as a service, so that you don't build or manage any infrastructure.

## Setting up the StepZen plugin

### Pre-requisites

- You have a [Netlify](http://netlify.com/) account and site
- You have a [StepZen account](http://stepzen.com/), and you know the account name and API Key
- You have installed the StepZen CLI tool `npm install -g stepzen` (optional, recommended )
- You have built a GraphQL API using StepZen. See [Quickstart in StepZen docs](https://stepzen.com/docs/quick-start). (optional, recommended)

### Install the plugin into your Netlify site

The plugin is available in the Netlify [Build Plugin directory](https://app.netlify.com/plugins). It is named `netlify-plugin-stepzen` on NPM and is hosted at [https://github.com/steprz/netlify-plugin-stepzen](https://github.com/steprz/netlify-plugin-stepzen)

Search for **StepZen** in the [Build Plugin directory](https://app.netlify.com/plugins), and click `install`
or
install it using the Netlify configuration file, which allows for more customization. Follow the instructions [here](https://docs.netlify.com/configure-builds/build-plugins/#file-based-installation).

### Configure the plugin

1. Create a stepzen directory containing your API specification. If you have built an API using StepZen, you can just copy the directory into your Netlify project root folder and name it stepzen.
1. Add three environment variables, as specified [here](https://docs.netlify.com/configure-builds/environment-variables/#declare-variables):
   - `STEPZEN_ACCOUNT` specifies the name of your StepZen account;
   - `STEPZEN_ADMIN_KEY` specifies the admin API Key that enables access to that account's endpoint.
   - `STEPZEN_NAME` specifies a name that StepZen uses for the resources related to this project.
1. Optionally, you can specify two other environment variables.

   - `STEPZEN_FOLDER` is a folder within StepZen for project resources (this defaults to netlify)
   - `STEPZEN_CONFIGURATION_SETS` is a list of [StepZen configuration sets](/docs/design-a-graphql-schema#3--create-your-configuration-file) to apply to your schema definitions. This is specified as a comma-separated string and defaults to `netlify/configuration,stepzen/defaults`.

     If you do not specify `STEPZEN_CONFIGURATION_SETS`, remember to name the configuration set you upload to StepZen as `netlify/configuration`. If you use more than one configuration set with your API, you must specify this environment variable.

1. It's done!

## How it works

1. When you push changes to the main branch on GitHub (for cases where the source is stored in GitHub), GitHub calls a Netlify hook. (It works the same way if your source materials are in GitLab, or Bitbucket.)
1. The hook triggers a checkout, build, and push on Netlify and results in the updated website served by the Netlify CDN.

   1. The build first establishes the build environment specified in the netlify.toml file, but before triggering the build process, it triggers the StepZen plugin.
   1. The build plugin compiles and pushes the contents of the GraphQL schema files (SDLs), which are contained in the `stepzen` directory, to the corresponding StepZen account.
   1. The site build process begins. Because the site build process is triggered after the StepZen plugin, StepZen APIs are available during the static build.
   1. Netlify completes the build and pushes the site to the Netlify CDN. Once the push completes successfully, the StepZen endpoint includes the updated GraphQL schema (SDL) code and is serving the new API.

This StepZen-Netlify integration simplifies your deployment. The workflow you use to deploy changes on Netlify does not change. You manage your GraphQL schemas (SDLs) in a cohesive way with the rest of the Netlify site and your releases are coordinated.

At runtime, StepZen ensures that API keys and queries are protected when making calls from a browser to retrieve and render data on the client-side. You don't need to write code to parallelize execution, store keys safely, handle caching, and more.

## Where to go from here?

Have a number of APIs and backends powering your Jamstack site? Deploying your site on Netlify? Simplify aggregating the data from backend data sources by building a unified GraphQL API on StepZen and give the build plugin a try.

- StepZen [Free Sign Up](https://stepzen.com/signup)
- [Install](https://app.netlify.com/plugins) the Netlify plugin

---

We’re honored to be featured as the [Netlify Plugin of the Week](https://netlify.com/blog/2021/05/14/netlify-build-plugin-of-the-week-stepzen/). Thank you, Jessica, and the entire Netlify team for an awesome collaboration!


Using the StepZen Netlify build plugin, the deployment of a single GraphQL endpoint, built on StepZen, is simple and seamless, and happens within your Netlify build.


Deploy a StepZen GraphQL API in Your Netlify Build


[RedwoodJS](http://redwoodjs.com/) is a fullstack, serverless web application framework for building and deploying Jamstack applications. Imagine a React frontend, statically delivered from a CDN, talking via GraphQL to a backend running on AWS Lambdas, all deployable with `git push`.

[StepZen](https://stepzen.com) makes it easy to build and deploy a GraphQL backend that you can connect your RedwoodJS site to. It allows you to pull data from any backend including REST APIs and databases and connect them together into a single GraphQL API endpoint.

In this article, we will create and deploy a GraphQL API using StepZen that connects to a Shopify backend and then consume that API in a React frontend built with RedwoodJS and deployed on a static hosting provider. Redwood's `api` side is auto-configured with a GraphQL handler that can be deployed with serverless functions, enabling [secure API routes](https://stepzen.com/blog/how-to-secure-api-routes-for-jamstack-sites).

## Setup

We'll use [Yarn](https://classic.yarnpkg.com/en/docs/install), which is a requirement for RedwoodJS, to create the basic structure of our app.

```bash
yarn create redwood-app stepzen-redwood-shopify
```

This creates a new directory, `stepzen-redwood-shopify`, containing several subdirectories and files.

### Fire it up

Navigate into your project and start the development server.

```bash
cd stepzen-redwood-shopify
yarn rw dev
```

Once the project builds, your browser should automatically open to `http://localhost:8910` to show the web app running locally.

![the default Redwood site](/images/blog/redwoord-start.png)

The Lambda functions are running on `http://localhost:8911` as well as being proxied to `http://localhost:8910/.redwood/functions/*`.

![Redwood Lambda Functions running locally](/images/blog/redwood-lambda.png)

### Default Project Structure

If you open the project, you should see the following file and folders.

```
├── api
│   ├── src
│   │   ├── functions
│   │   │   └── graphql.js
│   │   ├── graphql
│   │   ├── lib
│   │   │   └── db.js
│   │   └── services
└── web
    ├── public
    │   ├── README.md
    │   ├── favicon.png
    │   └── robots.txt
    └── src
        ├── components
        ├── layouts
        ├── pages
        │   ├── FatalErrorPage
        │   │   └── FatalErrorPage.js
        │   └── NotFoundPage
        │       └── NotFoundPage.js
        ├── App.js
        ├── Routes.js
        ├── index.css
        └── index.html
```

## StepZen Side

Now let's set up the GraphQL API within StepZen. A StepZen project contains the following files:

- `index.graphql` tells StepZen how to assemble the various type definition files into a complete GraphQL schema.
- One or more GraphQL Schema Definition Language (SDL) files ending in `.graphql`.
- `config.yaml` contains the keys and other credential information that StepZen needs to access your backend data sources.

To setup our StepZen API, let's create a `stepzen` directory within our Redwood project's API folder. Within the `stepzen` folder, create a `schema` directory.

```bash
mkdir api/stepzen api/stepzen/schema
```

Every StepZen project requires an `index.graphql` that ties together all of our schemas. Create an `index.graphql` file for our `schema` and a `products.graphql` file for our `Product` type and `Query` type.

```bash
touch api/stepzen/schema/products.graphql api/stepzen/index.graphql
```

### `products.graphql`

Let's create a product GraphQL type that will represent a product being returned by the Shopify API. `products.graphql` will have a `Product` type and a `products` query that returns an array of `Product` objects. Our product type only has a few properties.

```graphql
# api/stepzen/shopify/products.graphql

type Product {
  id: ID!
  handle: String
  title: String
}
```

Our `products` query will be connected to the Shopify REST API using StepZen's custom `@rest` directive. The `@rest` directive accepts the URL of the REST `endpoint` that we'd like to connect it to.

```graphql
# api/stepzen/shopify/products.graphql

type Query {
  products: [Product]
    @rest(
      resultroot: "products[]"
      endpoint: "https://$api_key:$api_password@$store_name.myshopify.com/admin/api/2020-01/products.json"
      configuration: "shopify_config"
    )
}
```

Let's look at what each of these configuration properties does:

- `resultroot` - tells StepZen the root of the data in the JSON object returned by the REST API, in this case it is an array of products `products[]`
- `endpoint` - the REST URL you want to call. Values preceeded by the `$` in this string are replaced by query arguments or configuration properties.
- `configuration` - these are the details within the `config.yaml` file and can include anything you want to pass down to headers (ex. Authorization) and/or stuff that you do not want to write in your SDL.

### `index.graphql`

Our `schema` in `index.graphql` ties together all of our other schema files. For this example, we just have the `products.graphql` file included in our `@sdl` directive.

```graphql
# api/stepzen/index.graphql

schema @sdl(files: ["schema/products.graphql"]) {
  query: Query
}
```

The `index.graphql` tells StepZen how to assemble the various type definition files into a complete GraphQL schema. The `@sdl` directive is a StepZen directive that specifies the list of files to assemble. It includes a comma-separated list of `.graphql` files in your project folder.

### `config.yaml`

The `config.yaml` contains various configurations that can include the keys and other credential information that StepZen needs to access your backend data sources.

```bash
touch api/stepzen/config.yaml
```

This file should be added to `.gitignore` as it likely contains secret information.

```bash
.idea
.DS_Store
.env
.netlify
.redwood
dev.db
dist
dist-babel
node_modules
yarn-error.log
web/public/mockServiceWorker.js
config.yaml
```

To connect a Shopify account, we'll need to supply our `api_key`, `api_password`, and `store_name`.

```yaml
configurationset:
  - configuration:
      name: shopify_config
      api_key: <YOUR_API_KEY>
      api_password: <YOUR_API_PASSWORD>
      store_name: <YOUR_STORE_NAME>
```

You can get this information in your Shopify account.

### Deploy Our StepZen Endpoint

Now that our schema has been created, we can use the StepZen CLI to install it. If you have not already installed and configured the StepZen CLI, you can follow the [instructions here](http://stepzen.com/docs/quick-start#install-the-stepzen-cli).

```bash
cd api/stepzen
stepzen start
```

This will deploy the schema to StepZen, and makes it available on the StepZen dashboard where you can explore the endpoint. It will also watch the directory or changes so that any changes that you make to your schema code will be automatically uploaded and redeployed.

Note that if this is the first time you deployed this schema, you'll be asked to give it a name in the format `[folder-name]/[endpoint-name]`. We can name our `api/shopify`. Once the site deploys, take note of the endpoint URL for your GraphQL API. You can get this in the console. It will look like the following:

```bash
Deploying to StepZen...... done

Successfully deployed api/shopify at 4:22:19 PM

Your endpoint is available at https://biggs.stepzen.net/api/shopify/__graphql
```

### Query the GraphQL Endpoint

Let's test our GraphQL API by using the GraphQL explorer to query it. The following `ProductsQuery` returns an array of `Product` objects with the `title`, `id`, and `handle` for each product.

```graphql
query ProductsQuery {
  products {
    title
    id
    handle
  }
}
```

If you've populated some products in Shopify, you should see a query result similar to the following.

![product query results](/images/blog/redwood-products-query.png)

> The default way to test your GraphQL endpoint is from the [StepZen dashboard explorer](https://dashboard.stepzen.com/explorer). You can get a local GraphiQL IDE by running `stepzen start` with the `--dashboard=local` flag.

Now that we've created our API, we need to connect Redwood with StepZen to get the data into our web app.

## The Redwood API Side

The `api/src` directory contains all the other backend code for a Redwood app and includes four directories:

- `functions`
- `graphql`
- `lib`
- `services`

The `functions` directory contains a `graphql.js` file auto-generated by Redwood that is required to use the GraphQL API. Since we will not use the Prisma client or a database that Redwood comes preconfigured for, we can replace the default template with the following code.

```javascript
// api/src/functions/graphql.js

import {
  createGraphQLHandler,
  makeMergedSchema,
  makeServices,
} from '@redwoodjs/api'

import schemas from 'src/graphql/**/*.{js,ts}'
import services from 'src/services/**/*.{js,ts}'

export const handler = createGraphQLHandler({
  schema: makeMergedSchema({
    schemas,
    services: makeServices({ services }),
  }),
})
```

### `products.sdl.js`

The `graphql` directory contains `products.sdl.js` with your GraphQL schema written in the Schema Definition Language. This will ensure that our Redwood API will have a `schema` that matches our `schema` in `products.graphql`.

```bash
touch api/src/graphql/products.sdl.js
```

The schema includes a `Product` type, and each `Product` has an `id`, `handle`, and `title` just like our StepZen schema. The `products` query returns an array of `Product` objects.

```javascript
// api/src/graphql/products.sdl.js

export const schema = gql`
  type Product {
    id: ID
    handle: String
    title: String
  }

  type Query {
    products: [Product]
  }
`
```

### `client.js`

The `lib` directory contains two files by default:

- `db.js` for importing the [Prisma client](https://www.prisma.io/docs/concepts/components/prisma-client)
- `logger.js` for using the [Redwood logger](https://redwoodjs.com/docs/logger)

While Redwood's `web` side includes Apollo Client by default, its `api` side does not include any built in mechanism for making HTTP requests. There are two common solutions to this for Redwood applications.

- The first solution, demonstrated in the Redwood documentation, includes using [`node-fetch`](https://redwoodjs.com/cookbook/using-a-third-party-api#the-service).
- We will follow the model of numerous community projects that have used `graphql-request` to connect to services such as [Contentful](https://community.redwoodjs.com/t/what-dbs-does-redwood-support/143/14), [AppSync](https://community.redwoodjs.com/t/how-can-i-wire-up-a-graphql-api-to-redwoodjs/1112), [Hasura](https://community.redwoodjs.com/t/building-a-minimum-viable-stack-with-redwoodjs-and-faunadb/1048/11), and [FaunaDB](https://community.redwoodjs.com/t/building-a-minimum-viable-stack-with-redwoodjs-and-faunadb/1048).

First, we need to install `graphql-request` as a dependency on the `api` side.

```bash
yarn workspace api add graphql-request
```

Since we will not be using the Prisma Client we can rename `db.js` to `client.js` and include the following code. This code uses `graphql-request` to connect to StepZen and pass our StepZen API key in the headers and the query being sent to the API.

```javascript
// api/src/lib/client.js

import { GraphQLClient } from 'graphql-request'

export const request = async (query = {}) => {
  const endpoint = process.env.API_ENDPOINT

  const graphQLClient = new GraphQLClient(endpoint, {
    headers: {
      authorization: 'apikey ' + process.env.API_KEY,
    },
  })
  try {
    return await graphQLClient.request(query)
  } catch (err) {
    console.log(err)
    return err
  }
}
```

- `endpoint` is set to the url generated when we deployed our API with `stepzen start`.
- `authorization` includes your StepZen API key appended to `apikey`. You can get your API key on your [dashboard page](https://dashboard.stepzen.com/account).

### Create `.env` file

Let's create the `.env` file that will contain our StepZen API key and endpoint URL.

```bash
touch .env
```

```
API_ENDPOINT=<YOUR_API_ENDPOINT>
API_KEY=<YOUR_API_KEY>
```

### `products.js`

In the `services` directory we will create a `products` directory with a `products.js` service. This file will be the one that sends the GraphQL query to our API.

```bash
mkdir api/src/services/products
touch api/src/services/products/products.js
```

We will include code for querying data with GraphQL.

```javascript
// api/src/services/products/products.js

import { request } from 'src/lib/client'
import { gql } from 'graphql-request'

export const products = async () => {
  const GET_PRODUCTS_QUERY = gql`
    query getProducts {
      products {
        title
        id
        handle
      }
    }
  `

  const data = await request(GET_PRODUCTS_QUERY)

  return data['products']
}
```

`GET_PRODUCTS_QUERY` is sent with the `GraphQLClient` imported from `src/lib/client`. The query is asking for the list of `products` and their `title`, `id`, and `handle`.

## The Redwood Web Side

Now that the API and query are set up, we need to connect the web interface to display the returned data. The `web` side contains a `ProductsCell` for fetching `products` and a `HomePage` for rendering the cell.

### `ProductsCell`

We can use yarn to create the `ProductsCell.js` file.

```bash
yarn rw g cell products
```

`ProductsQuery` returns the `id`, `title`, and `handle` of each `Product`. This will send the query to our `api` side, which in turn sends a query to our StepZen API. Once the results are returned, they will be output on the page (we've also added some very basic handling of the loading, empty and failure states).

```jsx
// web/src/components/ProductsCell/ProductsCell.js

export const QUERY = gql`
  query ProductsQuery {
    products {
      id
      title
      handle
    }
  }
`

export const Loading = () => <div>Almost there...</div>
export const Empty = () => <div>WE NEED PRODUCTS</div>
export const Failure = ({ error }) => <div>{error.message}</div>

export const Success = ({ products }) => {
  return (
    <ul>
      {products.map((product) => (
        <li>{product.title}</li>
      ))}
    </ul>
  )
}
```

### `HomePage`

Finally, let's create the home page.

```bash
yarn rw g page home /
```

All we need to do in this file is import `ProductsCell` to display the information fetched by the cell's query.

```jsx
// web/src/pages/HomePage/HomePage.js

import ProductsCell from 'src/components/ProductsCell'

const HomePage = () => {
  return (
    <>
      <h1>StepZen+Redwood and Shopify</h1>

      <h2>Products</h2>

      <ProductsCell />
    </>
  )
}

export default HomePage
```

![05-home-page-localhost](/images/blog/redwood-shopify-done.png)

### Finished Project Structure

```
├── api
│   ├── src
│   │   ├── functions
│   │   │   └── graphql.js
│   │   ├── graphql
│   │   │   └── products.sdl.js
│   │   ├── lib
│   │   │   └── client.js
│   │   └── services
│   │       └── products
│   │           └── products.js
│   └── stepzen
│       ├── shopify
│       │   └── products.graphql
│       └── index.graphql
└── web
    ├── public
    │   ├── README.md
    │   ├── favicon.png
    │   └── robots.txt
    └── src
        ├── components
        │   └── ProductsCell
        │       ├── ProductsCell.js
        │       ├── ProductsCell.mock.js
        │       ├── ProductsCell.stories.js
        │       └── ProductsCell.test.js
        ├── layouts
        ├── pages
        │   ├── FatalErrorPage
        │   │   └── FatalErrorPage.js
        │   ├── HomePage
        │   │   └── HomePage.js
        │   └── NotFoundPage
        │       └── NotFoundPage.js
        ├── App.js
        ├── Routes.js
        ├── index.css
        └── index.html
```

## Deploy to Netlify

Redwood provides helpful setup commands to deploy to various hosting providers. We will deploy our project with [Netlify](https://redwoodjs.com/docs/deploy#netlify-deploy).

- Depending on your needs you can configure your project to be deploy on [Vercel](https://redwoodjs.com/docs/deploy#vercel-deploy), [Render](https://community.redwoodjs.com/t/using-render-com-instead-of-netlify-and-heroku/728/4), or [Heroku](https://community.redwoodjs.com/t/self-host-on-heroku/1765/4).
- If you're particularly adventurous and enjoy configuring Linux servers you can even host it yourself with [PM2 and Nginx](https://redwoodjs.com/cookbook/self-hosting-redwood).
- If you're a little less adventurous but still want some servers in your life you can run a Docker container with [Dokku](https://community.redwoodjs.com/t/selfhosting-redwood-using-dokku/1998).

### Setup command

The following command will generate the configuration file needed to deploy to Netlify.

```bash
yarn rw setup deploy netlify
```

This generates the following `netlify.toml` file:

```toml
[build]
  command = "yarn rw deploy netlify"
  publish = "web/dist"
  functions = "api/dist/functions"

[dev]
  command = "yarn rw dev"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
```

This lets Netlify know that:

- Your `build` command is `yarn rw deploy netlify`
- The `publish` directory for your assets is `web/dist`
- Your `functions` will be in `api/dist/functions`

All that's left to do is push the project to a repository like GitHub and connect that to your Netlify account. Netlify will build and deploy the project for you using the settings provided.

## Where to Go From Here

Our example was purposefully simple, but the next steps would be to build out a more complete Shopify schema and deploy it to StepZen to get all the data that Shopify provides. We'd also want to build a more complete frontend to display our products. If you'd like to learn more about StepZen and how to build a schema, visit the [StepZen docs](https://stepzen.com/docs). To learn more about how to configure Redwood and build the frontend, visit the [Redwood docs](https://redwoodjs.com/docs/introduction).

You can find more example repositories at the [StepZen Github](http://github.com/stepzen-dev). If you're not already signed up for StepZen, you can sign up [here](https://www.stepzen.com/signup).


Build a site that pulls data from the Shopify API using StepZen and connects it to Redwood's API side which is auto-configured with a GraphQL handler that can be deployed with serverless functions enabling secure API routes.


Building Fullstack eCommerce Apps with RedwoodJS, Shopify, and StepZen


# How To Build a GraphQL API Connected to a MySQL Database Using StepZen

GraphQL makes your life easy. As opposed to using a REST paradigm to access your datasource, you don't have to filter out data you don't need.

You ask for what you want:

```graphql

    {
    fruit(id: 1){
        name
        isPoisonous
        }
    }

```

and you get back exactly that.

```graphql
    {
    "fruit": {
        "name": "banana",
        "isPoisonous": false
        }
    }
```

Now, if you add StepZen to the mix, you can query your database in a similar way — and for simple queries, you won't have to write a line of SQL.

You'll also save on the codespace you need to set up your connection. Let's see how.

## Getting Set Up

To follow along with the steps in this post, you'll first need to sign up for a [StepZen account](https://stepzen.com/signup). That way, you'll be able to access your StepZen admin and API keys from your account page.

Then, you'll need to have a database that is deployed to Heroku. If you don't have one, you can follow these instructions to get one set up:

1. Download MySQL workbench [before you start](https://dev.mysql.com/downloads/). You should also have MySQL installed on your machine in order to use the workbench.

2. Sign up for [a Heroku account](https://signup.heroku.com/). It can be on the free tier, but you'll need to add a credit card to your account to use the add-ons that you need (it won't be charged as a part of this tutorial). Once you've done that, you can proceed.

3. Go to your dashboard and click 'New', then 'Create New App'. Type in your app name and hit 'Create App'.

4. Click on the 'Resources' tab and search for 'ClearDB MySQL' under 'Add-ons'. Click on it and select the 'Ignite-Free' plan and then 'Submit Order Form'.

5. Now click 'Settings' and 'Reveal Config Vars'. For the value of `CLEARDB_DATABASE_URL` you should see a string formatted like `mysql://USERNAME:PASSWORD@HOSTNAME/DB_NAME`. You'll use this info for setting up a new connection in your MySQL Workbench in the next few steps.

>NOTE: in the `DB_NAME`, leave off the `?` and everything after it.

### Seeding your database from MySQL Workbench

If you've already got your own database with data in it, then you can follow along with our instructions using it. If you don't have data in your database, you'll need to seed it with data first by following these instructions:

1. Open up MySQL workbench.
* Click the home icon at the top left corner.
* Next to 'MySQL Connections' click the + button, then name your connection whatever you want
* Enter the `USERNAME` and `HOSTNAME` from your heroku account. You can leave the port as it is.
* Click 'Store in Keychain'and add your `PASSWORD`.
* Click 'Test Connection'.  You won't need a default schema.
* Once you hit 'OK' on the notification that your connection was successful, hit 'OK' again.
* Click on your connection to open it.

2. Click the 'schemas' tab on the top left. Double click the name of your schema on the left to make sure it is selected, and copy and paste this code:

```sql
CREATE TABLE `authors` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(45) NOT NULL,
  `isPseudonym` tinyint(4) DEFAULT '0',
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

CREATE TABLE `books` (
  `id` int(11) NOT NULL,
  `name` varchar(45) NOT NULL,
  `originalPublishingDate` date NOT NULL,
  `authorID` int(11) DEFAULT NULL,
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

INSERT INTO `authors`
VALUES
(1,'Agatha Christie',0),
(2,'Sir Arthur Conan Doyle',0),
(3,'Edgar Allan Poe',0);

INSERT INTO `books`
VALUES
(1,'Murder on the Orient Express','1934-01-01', 1),
(2,'The Mysterious Affair at Styles','1920-10-01', 1),
(3,'The Adventure of the Three Garridebs','1924-10-25', 2),
(4,'The Murders in the Rue Morge','1841-04-04', 3);
```

3. Make sure it is either 1) all selected or 2) not selected at all and click the little lightning bolt under the Query 1 tab. This will run the SQL code that seeds your database.

4. Query the database to verify the seed data was entered:

```sql
SELECT * FROM authors
```

![SQL query response](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3ytpjr9pqtppntjcvv8x.png)


### Set yourself up with StepZen

You'll need a StepZen account. If you don't already have one, you can [request an invite here](https://stepzen.com/signup).

### Install StepZen CLI

The StepZen CLI will allow you to easily upload, deploy and test your GraphQL API. It can be installed globally via npm.

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

### Login to StepZen account

Before you can deploy to StepZen, the CLI will need your account information, which can be added via the `login` command.

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

You'll need your account name and admin key, which are accessible via your ["Dashboard" page](https://dashboard.stepzen.com/account).

## Let's get started on connecting MySQL

First we need to set some configuration. Create a file called `.gitignore` In the same folder as this project, make a file called `config.yaml` Then add `config.yaml` to your .gitignore to keep it from being committed. It's private info! :key:

This is what you'll place in it:

```yaml
configurationset:
  - configuration:
      name: MySQL_config
      dsn: USERNAME:PASSWORD@tcp(HOSTNAME)/DB_NAME
```
What does this code do? It provides StepZen the information it needs to connect to your database.

What's next? Let's dig into writing GraphQL files.

## GraphQL Files

We'll start with `book.graphql`, which is written in GraphQL Schema Definition Language.

You're going to see some code starting with the `@` symbol. These are [GraphQL directives](https://spec.graphql.org/June2018/#sec-Type-System.Directives). The two directives below are custom directives that the team at StepZen invented.

Notice the `@materializer` directive on the type. When we query `book`, we want to be able to see information on the book's `author` as well, and we're able to do this by using the materializer to query `author` and return the `name`. It will use the `authorID` field to find each `author`.

If you've got different data in different tables, you'll need a type for each table, which fields for the data you want to return from each table. You can use `@materializer` similarly to connect your tables, as well as `@dbquery` to query your database easily.

```graphql
type Book {
  id: ID!
  name: String!
  originalPublishingDate: Date!
  authorID: ID!
  author: Author
  @materializer(
        query: "author"
        arguments: [{ name: "id" field: "authorID"}]
  )
}
type Query {
  book(id: ID!): Book
        @dbquery(type: "mysql", table: "books", configuration: "MySQL_config")
  books(originalPublishingDate: Date!): [Book]
        @dbquery(
            type: "mysql",
            query: "SELECT * FROM books WHERE ? >= DATE '1900-00-00'",
            configuration: "MySQL_config"
        )
}


```

## What's in the query?

The `@dbquery` directive does a lot here. First, it tells StepZen that we're using a database query and that we're using MySQL.

In the first `@dbquery` directive, we only supply a `table` property because the table fields match the properties in our type. StepZen automaticaly assigns the right database field to the right property for us.

In the second directive, we need to customize the data that StepZen gets from the table, so we supply a `query` property. The query we pass, ` SELECT * FROM books WHERE ? >= DATE '1900-00-00` is a custom query that returns only books written in the 1900's and beyond. You can supply any type of query you want here, for example joining two tables together to populate a single type.


## Other Types

In `author.graphql`, we follow a similar pattern. You can write a type for each table in your database like this.

```graphql
type Author {
  id: ID!
  name: String!
  isPseudonym: Boolean!
}
type Query {
  author(id: ID!): Author
        @dbquery(type: "mysql", table: "authors", configuration: "MySQL_config")
  authors(isPseudonym: Boolean!): [Author]
        @dbquery(
            type: "mysql",
            query: "SELECT * FROM authors WHERE isPseudonym = ?",
            configuration: "MySQL_config"
        )
}
```

But how do we tell StepZen that we want to tie these different schema files together?

## Combining the Schema

That's where `index.graphql` comes in:

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

This file tells StepZen all of the files to combine to generate your GraphQL schema. And that's the last piece in the puzzle! :fireworks:

## Deploying to StepZen

Upload your config.

```bash
stepzen upload configurationset {{PROJECT_FOLDER_NAME}}/config --file=./config.yaml
```

Upload your schema and deploy to StepZen.

```bash
stepzen upload schema {{PROJECT_FOLDER_NAME}}/schema --dir=. &&
stepzen deploy {{PROJECT_FOLDER_NAME}}/api --schema={{PROJECT_FOLDER_NAME}}/schema --configurationsets={{PROJECT_FOLDER_NAME}}/config
```

## The StepZen GraphiQL Query Editor

In your terminal you can now you run:

```bash
stepzen start --dashboard=local
```

> The default way to test your GraphQL endpoint is from the [StepZen dashboard](https://dashboard.stepzen.com). You can get a local GraphiQL IDE by running `stepzen start` with the `--dashboard=local` flag.

Name your endpoint, and then StepZen will create a GraphiQL query editor on `localhost:5001` that is connected to your database!

So, if you had a database with a book table as well as an author table, pasting this code into your query editor:

```graphql
{
  book(id: 1) {
    id
    author {
      id
    }
  }
}
```

Would get you a result like:

![GraphQL query response](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/puq3k1sgjczsq4i0tv8o.png)

## Where to go from here
If you have questions about MySQL and StepZen, feel free to [consult the `@dbquery` docs](https://stepzen.com/docs/features/connect-a-database). If you want to download the code from this blog post, [check out our sample schema](https://github.com/stepzen-dev/stepzen-mysql).


Here, we give you an in-depth look at how you can easily use StepZen to connect your MySQL database to a GraphQL API.


How to Build a GraphQL API Connected to A MySQL Database Using StepZen


This example showcases the Next.js [Static Generation](https://nextjs.org/docs/basic-features/pages) feature using a GraphQL API built on StepZen to query the data sources -- [WordPress](https://wordpress.org) is the CMS backend to hold our blog posts, and [Cloudinary](https://cloudinary.com/) the source for images. We use Next.js to statically generate the posts.

To get started, sign in to your StepZen Account. If you don't have an account you can
[sign up for free](https://stepzen.com/signup) . You can view a [demo on Vercel](https://next-blog-wordpress.now.sh) and the repository at [StepZen Samples](https://github.com/stepzen-dev/stepzen-wordpress-nextjs/).

![01-homepage-demo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/t5vimjhly87sgupeajjv.png)

## 1. Prepare your WordPress site

Inside your WordPress admin, go to **Posts** and start adding new posts. Only published posts and public fields will be rendered.

1. Create at least **2 posts** with dummy data for content
2. Pick an author from your WordPress users
3. Add a **Featured Image**. You can download one from [Unsplash](https://unsplash.com/)
4. Fill the **Excerpt** field
5. When you’re done, make sure to **Publish** the posts

![03-new-post](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z4kpj9xb7u38totk16s5.png)

## 2. Create a Schema for Combining WordPress and Cloudinary Data with StepZen Import

StepZen makes it easy to build a single GraphQL API that combines data from any backend data source in a unified API. StepZen comes with API Templates that are pre-made GraphQL schemas configured with types, queries, and backends, designed to be combined, customized, and extended and help you quickly create your GraphQL API.

The `stepzen import` command imports one or more template schemas to start your project. API Templates are pre-made GraphQL schemas configured with types, queries, and backends, designed to be combined, customized, and extended and give you a jumpstart creating your unified GraphQL API. In this case, we import the `WordPress` and `Cloudinary` templates, which can be viewed on our [StepZen Schemas repository](https://github.com/steprz/stepzen-schemas).

### Install `stepzen` CLI and create project directory

```bash
npm install -g stepzen
mkdir wp-stepzen && cd wp-stepzen
```

### Import WordPress Template

```bash
stepzen import wordpress
```

For WordPress you will be asked to include your WordPress `username` and `password`.

```
What is the wordpress username? [hidden]
What is the wordpress password? [hidden]
```

### Import Cloudinary Template

```bash
stepzen import cloudinary
```

For Cloudinary you will be asked to include your Cloudinary `api_key`, `api_secret`, and `cloud_name`.

```
What is the api_key for your cloudinary API? [hidden]
What is the api_secret for your cloudinary API? [hidden]
What is the cloud_name for your cloudinary API? [hidden]
```

### config.yaml

This will generate a `config.yaml` file containing the keys and other credential information that StepZen needs to access your backend data sources. This file should be added to `.gitignore` as it contains secret information.

```yaml
configurationset:
  - configuration:
      name: wordpress_config
      username: { { username } }
      password: { { password } }
  - configuration:
      name: cloudinary_config
      api_key: { { api_key } }
      api_secret: { { api_secret } }
      cloud_name: { { cloud_name } }
```

### index.graphql

Every StepZen project requires an `index.graphql`. This file defines all the files that make up the unified GraphQL schema. If you don't want to include Cloudinary, comment it out.

```graphql
schema
  @sdl(
    files: [
      "wordpress/posts.graphql"
      "wordpress/pages.graphql"
      "cloudinary/cloudinary.graphql"
    ]
  ) {
  query: Query
}
```

## 3. Query Your WordPress and Cloudinary Backends

`stepzen start` uploads and deploys your GraphQL endpoint while watching the project for changes. In your root folder run:

```bash
stepzen start
```

From the StepZen dashboard, you can view the GraphQL API and test your queries. For example, enter the following query:

```graphql
{
  wordpressPages {
    id
    title
    content
    featuredImage
    slug
  }

  wordpressPosts {
    id
    title
    content
    featuredImage
    slug
  }
}
```

## 4. Setting up Cloudinary Images

To include images from Cloudinary you will first need to [create a Cloudinary account](https://cloudinary.com/users/register/free). Once you have created an account you will have access to your Cloudinary Dashboard.

![cloudinary-dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pbc3tuimelranlxulk3p.jpg)

In the top right where it says {{Cloud Name}}, you will see your own cloud name for your config.

![cloundinary-images](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gope3vlb2cyjfsz3151g.png)

Add all the images you want to feature on your pages with the slug of the matching post and page. The images are named to align with the slug of the WordPress page.

- **WordPress URL** - `https://yoursite.com/post/hello-world`
- **Image Name (PublicId)** - `hello-world`

Uncomment the `cloudinaryImage` data found on `index.js` and `[slug].js` for `getStaticProps` and `coverImage`. Then delete `{post.featuredImage}` found on `index.js` and `[slug].js` and save the project.

## 5. Next.js Configurations

To configure our Next.js site we will need to create a file to hold our environment variables. Copy the `.env.local.example` file in this directory to `.env.local` (you will also want to include this in your `.gitignore` file):

```bash
cp .env.local.example .env.local
```

Open `.env.local` and set `STEPZEN_API_URL` to be the URL to your GraphQL endpoint in WordPress. For example: `https://{stepzenid}.stepzen.net/tutorials/helloworld/__graphql`.

```bash
STEPZEN_API_URL=<YOUR_API_URL>
STEPZEN_AUTH_REFRESH_TOKEN=<YOUR_REFRESH_TOKEN>
```

### Run Next.js in development mode

To run Next.js in development mode with `npm`, enter the following command.

```bash
npm i && npm run dev
```

If you are using `yarn` instead of `npm`, enter the following command.

```bash
yarn && yarn dev
```

Your blog should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, leave us a note on [GitHub Issues](https://github.com/stepzen-dev/stepzen-wordpress-nextjs/issues).

## 6. Deploy on Vercel

You can deploy this app to the cloud by pushing it to GitHub/GitLab/Bitbucket and [importing to Vercel](https://nextjs.org/docs/deployment).

For more detailed setup instructions you can checkout the README on the [stepzen-wordpress-nextjs](https://github.com/stepzen-dev/stepzen-wordpress-nextjs) repo at the [StepZen Github](https://github.com/stepzen-dev/stepzen-wordpress-nextjs/). You can also checkout a deployed example at [next-blog-wordpress.now.sh](https://next-blog-wordpress.now.sh).


This example showcases Next.js ability to statically generate blog post by querying a GraphQL API built with StepZen that returns blog posts from WordPress and images from Cloudinary.


Building a Jamstack Blog with Next.js, WordPress, and Cloudinary




The A in Jamstack stands for **APIs**. These are the first- or third-party APIs that are accessed at build-time using the static site generators, or on the client using JavaScript. They enable developers to hydrate both static and dynamic content with data from various backend sources. We'll explore how the APIs can truly be the first-class citizen in the Jamstack ecosystem - one that developers leverage effectively.

> *APIs are the sweet dynamics that sweeten a Jamstack application to be more than a “static site.” Web developers can use relatively simple HTTP calls to endpoints maintained and scaled by other providers, thereby abstracting away all of their server-side concerns*. ~[Jamstack Attack! Static Sites, Dynamic APIs, and a Killer DX](https://blog.readme.com/jamstack-static-sites-dynamic-apis-killer-dx/)

Developers use APIs and other direct access methods to get the data they need to build and deploy static Jamstack apps and sites. For example, for an eCommerce site you may get product information from Contentful, price information from an API connected to a MySQL database, and product reviews from MongoDB.

APIs are often used on the client when you want to access dynamic content from the browser. For example, you may have an API that determines the location of your users and therefore you might connect with IP-API (a popular API for determining the locations based on IP address). You may want to tailor your messages or offers based on the weather conditions, and so might connect with OpenWeatherMap’s or the AccuWeather API. You may want the latest, updated inventory, which might be different than the last snapshot of inventory at the time of the last static build.

![Static and Dynamic Build](/images/blog/static-dynamic-build.png)

APIs are not just the standard but a powerful way for developers to fetch and combine data during static and dynamic builds. We believe that the potential of APIs in Jamstack applications is fully realized when APIs are easy to build and run and can help developers seamlessly harmonize multiple data sources. Let’s look at some of the considerations.

## No Two APIs are the Same

There are lots of APIs, and each behaves differently. There are different syntax, authorizations, protocols, and kinds of responses. Many APIs are well-documented, and many are not. Beyond discovering the data and its shape, writing the logic to handle it, and other design and build-time considerations, there are run-time concerns that compound the complexity. For example, if you want to call an API from a browser you need to protect the key for that API because you do not want the key to leak into the browser. You must also ensure that the query being executed by the browser is not modified in the browser. For example, say that you have an API that returns available items for sale in a specific month - you want to avoid somebody manipulating the month parameter in the browser. Suddenly they can find out what products will be available for sale next month - potentially leaking competitive information.

So what do you do? You write a lambda or other serverless function, then deploy and maintain it to take care of the API in question. Then the key and queries for the second API also need to be protected. So you write and deploy another lambda function. And on and on for every additional backend.

Furthermore, you’ll want to effectively monitor backends and know about response and API changes, API key invalidity, performance degradations. You’ll need to scale to optimize your applications and route around errors, effectively and efficiently handle protocol translations, design caching, handle API keys, access control, and manage rate limits and SLAs effectively. You often need to stitch APIs together, and create logic like “If something happens, call this API, otherwise call this API.”

So you’re writing, deploying, and maintaining more and more complex code. All this results in a decent amount of work that you must do to build, manage, and secure your APIs and apps.

![Lambda Functions](/images/blog/lambda-functions-complexity.png)


See [How to Secure API Routes for Jamstack Sites](/blog/how-to-secure-api-routes-for-jamstack-sites) for a discussion on making asynchronous API calls in the browser straightforward, and the considerations for authentication, sharing and protecting API keys, restricting what users can do with your API, and more.

## GraphQL: An API of APIs

GraphQL is a natural API of APIs. It allows for different backend data sources and different ways of connecting those backends to be unified in the context of a single GraphQL endpoint. Therefore you can fetch a customer's information, their orders, and the delivery status of those orders all with one GraphQL API. This is one of the big reasons we chose to adopt GraphQL for StepZen.

![API of APIs](/images/blog/graphql-api-of-apis.png)

To fully leverage its power to abstract the complexity of backend APIs away, StepZen makes it easy to set up a GraphQL endpoint to query all your data and avoid the complications of myriad and varied backends. You don't need to be a GraphQL expert, build a GraphQL server, or understand resolvers. You can abstract away any backend - SQL and NoSQL databases, REST and GraphQL APIs, and more - and easily access all the backend data you need.

![As-a-Service](/images/blog/as-a-service-attributes.png)


The GraphQL API you build on StepZen runs on StepZen - meaning that you build and manage zero infrastructure. We ensure that API keys are stored safely, manage access control, monitor the backends for performance, parallelize the execution, and ensure that your API is always-on so that the customers of your Jamstack application are happy. Even as you design and build your GraphQL API, you can test and iterate it locally with a built-in continuous deployment process.

## Summary

We believe that you as a developer have to worry about a lot of things and therefore we strive to make it easy for you to get a GraphQL endpoint up and running. Because you build sites and apps that center on static assets and enable both static and dynamic interaction through APIs, we believe that the **A** in Jamstack is increasingly [best served](https://stepzen.com/blog/why-graphql/) by GraphQL for frontend and full-stack developers alike. With StepZen, you can safely call all the APIs you use for your static assets or the dynamic experience. There are no keys to manage, no infrastructure to run or maintain.

## Where to go from here

Check out the [demo section of the Jamstack-SF meetup video](https://youtu.be/GnCjbXqLV-o?t=615) where we used a simple application that shows all the orders for a customer and their delivery status to demo how the dynamic and statically built data is assembled to power the experience. You’ll see how to select a GraphQL schema (pre-configured with a connection to a backend) from our [API templates](/developers/api-templates) GitHub repository, combine it with GraphQL snippets from a private repository, and deploy the unified GraphQL endpoint that you can query to deliver a static and dynamic experience for your Jamstack site.

Not yet signed up for StepZen? Try it free here https://stepzen.com/signup.  We continue to add to our [API templates](/developers/api-templates) ecosystem so that you can grab a pre-built GraphQL API and have your endpoint up and running in minutes. 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).



APIs are a powerful way to fetch and combine data during static and dynamic builds. We believe that the potential of APIs in Jamstack applications is fully realized when APIs are easy to build and run and help developers seamlessly harmonize multiple data sources.


Realizing the Potential of the API in Jamstack

# How to Secure API Routes for Jamstack Sites
On the landing page of our website, https://stepzen.com, you see an example of a query that can be used to provide a weather forecast for a visitor to your website, using their IP address as basis for the location.

![Localized Weather Query](/images/blog/htsarfjs_localizedweather.png "Localized Weather Query")

StepZen makes building the API backend to support a query like this easy by allowing you to stitch together data coming from multiple external APIs. In this article, we'll look at how you can use a query like this to personalize a site built with the Jamstack.

## Putting it on the Web

If you're using server-side rendering for your website, you're all set. You can just call this API when you render requests and viola, you're done.

But what if we want to do this on a Jamstack website? The majority of a Jamstack site is pre-rendered at build time via an SSG, but personalized content like this would need to be retrieved and rendered on the client-side using API calls from the browser.

Today, making API calls from the browser is pretty easy. The [JavaScript fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) makes asynchronous API calls in the browser straightforward, but there are some things we should be concerned about:

* If the API I'm calling requires authentication, that authentication would be visible to any user visiting the page that makes the API call. I don't want to share my API keys with the world, so I'll need to figure out how to hide those.
* Depending on the API, I may want to restrict what users can do with it. In our example, I don't want users to be able to retrieve the weather for any location, I only want them to see the current conditions for their IP address. I pay for access to the API, and I don't want people to reverse engineer my website in order to reuse the API on my dime.

![Browser API Call](/images/blog/htsarfjs_jam1.png "Browser API Call")

Today, one of the best ways to accomplish both these goals is to use a serverless function, such as AWS Lambda, GCP Cloud Run or Netlify Functions, to make the backend API call. We're creating a simple "wrapper" API that our web app can call, which takes care of authentication to the backend API and limiting what can be done with the API. Curious users will be able to determine how to call our serverless function, but that's all they will be able to do.

![Browser Serverless Function Call](/images/blog/htsarfjs_jam2.png "Browser Serverless Function Call")

This is such a common pattern that some providers and frameworks have built automation to make this very easy. In the next section we'll look at a live example.

## Building the Site

Next.js is a React framework with support for static and server rendering, which makes building a Jamstack site with dynamic content easy. Additionally, Next.js has a feature called [API Routes](https://nextjs.org/docs/api-routes/introduction), which makes building an API straightforward. API Routes are treated differently than pages, are server-side only. We will use API Routes to define the code for our serverless function.

Netlify is a hosting platform that makes it simple to host static sites, but they also provide serverless functions via Netlify Functions. On top of that, they have a plugin for Next.js sites that automatically creates serverless functions for any of the Next.js /api pages.

We will build our weather example using Next.js, creating an API call to retrieve the weather for the visitor's IP address. We'll then host the site on Netlify, and have Netlify automatically turn our API into a serverless function. Then we'll inspect the client-side code, and see how we've hidden our API key and restricted the capability of the API.

Our code is here: https://github.com/carloseberhardt/weather-test

Let's look at the structure of that app quickly, and point out a few key items.
```
.
├── components
│   └── weather.js
├── pages
│   ├── api
│   │   └── weather.js
│   ├── _app.js
│   └── index.js
```

The first key part of our web app is a React component defined in `components/weather.js` that retrieves and displays the forecast:
```javascript
import fetch from 'unfetch'
import useSWR from 'swr'

const fetcher = url => fetch(url).then(r => r.json())

export default function Weather() {
    const { data, error } = useSWR('/api/weather', fetcher)
    if (error) return <div>failed to load</div>
    if (!data) return <div>loading...</div>
    return <div><p>In {data.location.city}, it feels like {data.location.weather.feelsLike} {data.location.weather.units} with {data.location.weather.description}.</p></div>
}
```

We're simply fetching the `/api/weather` endpoint. Since all backend calls are handled in that code, we don't need to hide any API keys, or worry about people misusing our backend API.

The second key part of the app is the API implementation in `pages/api/weather.js`. Since that code will be executed server-side, we can use API keys or other secrets, which we can set as environment variables. We can also implement logic that restricts how the backend service is called. In this case we supply weather based on the IP address of the request, rather than any location. This further limits the value of trying to re-use our API code, making it less attractive for abuse.

```javascript
import { GraphQLClient, gql } from 'graphql-request'

const { STEPZEN_URL, STEPZEN_KEY } = process.env
const REFERERS=["https://weather-test.c3b.dev/", "http://localhost:3000/"]
// default ip if we fail to resolve or are running locally.
let ip = "128.101.101.101"

const graphQLClient = new GraphQLClient(STEPZEN_URL, {
    headers: {
        authorization: `Apikey ${STEPZEN_KEY}`
    }
})

export default async (req, res) => {
    // log headers, just while debugging.
    console.log("headers: ", req.headers)

    // check sec-fetch-site header for same-origin
    if (req.headers["sec-fetch-site"] && req.headers["sec-fetch-site"] != "same-origin") {
        console.log("Not same-origin: ", req.headers["sec-fetch-site"])
        res.statusCode = 403
        res.send("FORBIDDEN")
        return
    } else if (! req.headers["sec-fetch-site"]) {
        // requiring sec-fetch-site header would current break on several popular browsers.
        // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site
    }

    // check referer header for known referrers
    if (req.headers["referer"] && ! REFERERS.includes(req.headers["referer"])) {
        console.log("Bad referer: ", req.headers["referer"])
        res.statusCode = 403
        res.send("FORBIDDEN")
        return
    }

    // query -- to find ip we check for x-forwarded-for header, then override that if the x-bb-ip header exists
    if (req.headers["x-forwarded-for"]) {
        ip = req.headers["x-forwarded-for"].split(',')[0]
    }
    if (req.headers["x-nf-client-connection-ip"]) {
        ip = req.headers["x-nf-client-connection-ip"]
    }
    let query = gql`
    {
        location(ip: "${ip}") {
            city
            weather {
                temp
                units
                feelsLike
                description
            }
        }
    }
    `

    try {
        const data = await graphQLClient.rawRequest(query)
        console.log(JSON.stringify(data))
        res.statusCode = 200
        res.json(data.data)
    } catch (error) {
        console.error("error:", error)
        res.statusCode = 500
        res.send("Server Error")
    }
}
```

Additionally, we've added a few checks to try to ensure the caller is coming from a known domain. Let's look at those a bit and talk about the limitations.

First, we check to see if the request has a `sec-fetch-site` header set to `same-origin`. The W3C has started some work on providing servers some context about how a request was made which would allow servers to decide to serve the request or not. `sec-fetch-site` is one of these. Not all browsers support this yet, so we don't block the request if it is not present. To learn more about this header, see here: [Fetch Metadata Request Headers](https://w3c.github.io/webappsec-fetch-metadata/).

Next we check to see if the `Referer` header matches what we've defined in the `REFERERS` const. This is a simple way to see if the request is coming from our site (or locally).

In both checks, we "fail open" (if the headers aren't present, we allow the request through). Since we're already limiting what can be done with the API, we are not that worried about someone calling it directly from curl, for example. We could change the checks to require the presence of these or other headers if we wanted to be more restrictive.

Of course, these header checks can be circumvented by a caller if they know to try setting headers appropriately. It's not a locked gate, just a latched gate.

Our code also retrieves the caller's IP using either the `X-Forwarded-For` header, or if it's present, the `x-nf-client-connection-ip` header, which as of writing, is a header Netlify provides for us. See [this community discussion topic](https://community.netlify.com/t/is-the-client-ip-header-going-to-be-supported-long-term/11203) for more information.

Finally, we execute the query against our StepZen endpoint.

## Deploying to Netlify
Now that we have the code for our site and our API-wrapping serverless function, we can deploy the site to Netlify. I'm not going to explain that process in detail, since Netlify has great documentation already: [Next on Netlify](https://www.netlify.com/with/nextjs/). I will point out a few things we do.

First, when setting up our site we add two environment variables that we use in our API function: `const { STEPZEN_URL, STEPZEN_KEY } = process.env`. These are set to the endpoint of our StepZen GraphQL API and our StepZen API key, respectively.

Secondly, we install a terrific plugin the Netlify team provides, the [Next.js Build Plugin](https://github.com/netlify/netlify-plugin-nextjs#readme). This plugin will automatically create Netlify functions for any pages in your app that require server-side rendering, including anything you put in the /pages/api directory. This means we don't need to do any work at all to get our app working. No deploying a function manually, etc. Simply hook up your github repo and away you go.

In this example I also mapped my site to a custom domain, but that's not necessary. Just remember to adjust the `REFERERS` constant appropriately if you try this with your own deployment.

Once deployed to Netlify I can call up the page at https://weather-test.c3b.dev/ and see the current conditions at a location based on my IP address.

![Screenshot of deployed web app](/images/blog/htsarfjs_weather-test.png "Weather test web app")

If I open up the developer console in my browser, I can see the fetch calls being executed with a request to https://weather-test.c3b.dev/api/weather:

![Dev tools showing request details](/images/blog/htsarfjs_devtools.png "Dev tools request inspection")

You can see that no authentication information or details about the capabilities of the underlying APIs are revealed to the user. And if I try to hit that API URL directly from my browser I'll get a `FORBIDDEN` response, since the referer header is incorrect.

## Recap
Tooling for building and deploying Jamstack apps is rapidly improving, but there are still some challenges with the "A" in Jamstack that need solving. Here we've looked at one way to approach hiding credentials and limiting capabilities to prevent your users from misusing your APIs.


Securing API routes for Jamstack sites is important. Here's one way to do it.


How to Secure API Routes for Jamstack Sites


While not explicitly connected with each other, GraphQL and the Jamstack seemingly have had histories that seem to be intertwined in large part because both have been linked in many ways to the rise of the React framework. While created in 2012 by Facebook, GraphQL was officially open sourced in 2015, two years after React, which also came from Facebook. GraphQL (as you may already know) is a query language for building and querying APIs. As of 2018, the GraphQL spec is maintained by the independent [GraphQL Foundation](https://foundation.graphql.org/).

Meanwhile the Jamstack is largely an architecture or methodology around building web sites that centers on static assets that allow for dynamic interaction through the use of JavaScript and APIs. The architecture was around for a few years prior but, in an effort led by Netlify, it was officially given the Jamstack name in 2016. While it does use APIs, it does not explicitly prescribe what sort of APIs, so there's no overarching connection to GraphQL. However, in 2015 Kyle Matthews released a React-based static site generator named [Gatsby](https://www.gatsbyjs.com/) that was built upon React and tightly integrated with GraphQL for its entire data layer. Although Gatsby is no longer the only static site generator to use GraphQL by default, Gatsby's fast-rising popularity ultimately linked GraphQL with the broader concept of the Jamstack.

Let's explore a couple of popular Jamstack tools and how they use GraphQL.

## Gatsby

[![Gatsby](/images/blog/gatsby.png)](https://gatsbyjs.com)

Let's start with Gatsby as, to my knowledge, it was the first to explicitly tie GraphQL with the creation of Jamstack applications (though, in truth, Jamstack was not yet a word when Gatsby first came out). Every Gatsby site comes with a data layer. Ideally all the data for a site flows through this layer, including file-based content stored in Markdown, JSON or YAML files as well as external GraphQL APIs or APIs and services connected via a plugin. And this data layer is entirely built upon GraphQL.

![Gatsby's embedded GraphiQL](/images/blog/graphiql_gatsby.png)

Although it [isn't a requirement](https://www.gatsbyjs.com/docs/how-to/querying-data/using-gatsby-without-graphql/) that your Gatsby site uses GraphQL to get its data, doing so comes with a [number of benefits](https://www.gatsbyjs.com/docs/why-gatsby-uses-graphql/) such that you are strongly encouraged to do so. Thus, every time you run `gatsby develop`, Gatsby not only spins up your site (typically at `localhost:8000`) but also spins up the GraphQL API for your site (typically accessible via `http://localhost:8000/___graphql` using the embedded GraphiQL editor).

For example, if you were to use Gatsby's [blog starter](https://github.com/gatsbyjs/gatsby-starter-blog), it uses file-based content in the form of Markdown files for each blog post that are stored in the `/content/blog` folder. It then uses the `gatsby-source-filesystem` plugin to add the frontmatter and content of these files into Gatsby's GraphQL data layer and then retrieves them using a query along the lines of:

```graphql
{
  allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
      nodes {
        excerpt
        fields {
          slug
        }
        frontmatter {
          date(formatString: "MMMM DD, YYYY")
          title
          description
        }
      }
    }
}
```

To learn more about how to use GraphQL in Gatsby, check out the [GraphQL API documentation](https://www.gatsbyjs.com/docs/reference/graphql-data-layer/graphql-api/).

## Gridsome

[![Gridsome](/images/blog/gridsome.png)](https://gridsome.org)

Gridsome shares a lot of feature and philosophical similarities to Gatsby, but it is built using the Vue framework. For instance, Gridsome focuses on being a static site generator, unlike some other framework-based tools that offer both server-side rendering (SSR) and static pre-rendering (SSG). It also has a strong first-party and community plugin ecosystem. And, it also has a data layer that is built upon GraphQL that you can explore using the built-in GraphQL Playground.

![Gridsome GraphQL](/images/blog/graphql_gridsome.png)

The GraphQL data layer is where all the data about a site is added by default, including site metadata and pages. Gridsome provides built in tools to add in data that is coming from outside sources. For instance, you can use `api.loadSource` hook in a `gridsome.server.js` in conjunction with Gridsome's [Data Store API](https://gridsome.org/docs/data-store-api/) to add data from an external API. Any data I add to the data layer via the Data Store API is immediately queryable using GraphQL.

For example, imagine I wanted to pull in all of the blog posts that I'd written on DEV (note that this example uses the unauthenticated endpoint to get a user's public posts). Here's my `gridsome.server.js`:

```javascript
const axios = require('axios');

module.exports = function(api) {
  api.loadSource(async (actions) => {
    const posts = await axios.get(
      'https://dev.to/api/articles?username=remotesynth'
    );

    const collection = actions.addCollection('DevPosts');

    for (const post of posts.data) {
      collection.addNode(post);
    }
  });
};

```

And now I can query the API using the generated `AllDevPosts` query:

```graphql
query {
  allDevPosts {
  	edges {
      node {
        title
        description
        url
      }
    }
  }
}
```

To learn more about how Gridsome uses GraphQL, check the [GraphQL data layer documentation](https://gridsome.org/docs/data-layer/).

## GraphQL in Other Jamstack Tools

Another more recent addition to the list of Jamstack static site generators that use GraphQL as their data layer is [RedwoodJS](https://redwoodjs.com/), which brings a Rails-like approach to building what they call "full stack Jamstack." RedwoodJS puts its data layer in what it calls [cells](https://redwoodjs.com/docs/cells) that must contain a GraphQL query.

Of course, GraphQL can be used in just about any other static site generator that is capable of parsing the JSON response (which is pretty much any of them). I only cover these specifically because they are built upon GraphQL as a core capability. However, Jamstack is more than just static site generators. The other key ingredient is APIs and services and GraphQL plays a large part in that as well. For instance, there are common tools that make GraphQL a foundational part of their offering like [Fauna](https://fauna.com/), which provides a data API for a Jamstack site, or [GraphCMS](https://graphcms.com/), which is a headless CMS built upon a GraphQL API.

At [StepZen](https://stepzen.com), we're also focused on the Jamstack and GraphQL by building tools that will make it easy for developers to combine all their backends into a single API endpoint built on GraphQL. We believe that GraphQL offers unique capabilities that make it ideal for a serverless, "Jamstack-ready" API layer that avoids the need for boilerplate functions. Because of this, we think GraphQL will increasingly become an integral part of the API layer of Jamstack - that the A in Jamstack will increasingly stand for GraphQL.


A look at the intertwined evolution of the Jamstack and GraphQL and how popular Jamstack tools are built upon a GraphQL foundation.
