StepZen's powerful command line interface (CLI) translates users’ commands like stepzen import curl or stepzen start into API calls that StepZen servers execute.

Drinking our own champagne

This blog describes how we transitioned the original REST API to a GraphQL API hosted on StepZen. Ongoing change in the StepZen backend data model, making the existing REST API obsolete meant we had a decidion to make. Instead of rewriting the exiting REST API code to match the backend changes, we built the new GraphQL API on top of a PostgreSQL database to match the new backend data model.

This allowed us to get a production-grade API running with almost zero development effort. Also, in doing so we follow the principle of "drinking our own Champagne", which is a nice way to that say we use exactly the same features as all our users do (and would experience the same issues should there be any).

This is a gradual transition without any disruption to our users. The only thing you might notice is that some of the CLI commands (e.g. stepzen start or stepzen deploy) become slightly faster.

Why we started with REST

With the tooling available at the time, REST was the most efficient approach to take when we built the first prototypes of StepZen in early 2020 because creating a handful of REST API endpoints required much less code than creating a GraphQL API. Spinning up a GraphQL server and creating resolvers for each property in the GraphQL schema can require a bunch of boilerplate code. Adding access control to the API can become another challenge when doing it manually.

The features available in StepZen today remove this complexity, and allow us to start with a database schema and automatically provision a production-grade GraphQL API layer on top.

The benefits of GraphQL

GraphQL allows faster iteration when building API clients, and reduces the network delay required to communicate with the backend. Given the current roadmap for the StepZen CLI, we anticipate that both will be important capabilities, though in the near-term fast iteration likely has higher impact.

The StepZen CLI supports different use cases when it calls the same /account endpoint. With REST, changing the endpoint response for one of the use cases would affect the other use cases as well. Also, that would require changes both on the backend and in the CLI. With GraphQL, a change like that can be done purely on the CLI side as long as all the needed data is already available in the GraphQL schema. That means fewer engineers are involved in the change and therefore releases are independent and happen more quickly.

In one case - with the /account endpoint - all the CLI needs in response is a simple boolean value confirming whether or not the given credentials are valid. In another case, it needs full account details, possibly including some information on the deployed endpoints. If we stayed with REST, we would have to split this endpoint into two or keep adding partially unnecessary data to the response.

The benefits of StepZen

Implementing a GraphQL server might quickly become a complicated task, and the amount of code to maintain is typically larger than that for a REST backend. So we need to be able to reap the benefits of GraphQL and avoid additional costs. This is where StepZen shines. The GraphQL API used by the StepZen CLI is created directly from the PostgreSQL database that hosts metadata such as user accounts, keys, endpoint schema, and configuration.

In this case, StepZen helps in three ways:

• It lets us use the existing database schema in GraphQL - the time between the first draft and the final version of the GraphQL schema is very short
• It provides all the necessary GraphQL resolvers automatically - there is no need to write any resolvers code
• It hosts a GraphQL API server in a highly-available cluster environment - so you don't need to set-up operations and monitoring for your API

Using stepzen import postgresql

We used stepzen import postgresql to create the first version of the GraphQL schema and then after a few manual adjustments got to the version we have in production today. It made the process very easy and saved us hours of effort.

Then, instead of writing resolvers by hand, we used stepzen deploy to upload the schema to StepZen and use the full power of the GraphQL engine inside StepZen to serve this schema for the CLI. The existing REST API is deprecated and will be removed when the transition is done. For us, this has several benefits — there is less code inside the StepZen backend to maintain, and any changes in the data model are translated to changes in the API more quickly, without us having to update the resolvers layer.

Summary

Check out the docs and Getting Started to learn more about using stepzen import to enable introspection of the backend data source and quick creation of your GraphQL schema.

We're always striving to improve StepZen and the StepZen CLI, and make it so that developers can build and deploy GraphQL quickly and efficiently. We release updates of StepZen product weekly, so expect new features to be added regularly. Follow us on Twitter or jump into our Discord community to stay updated, ask questions or share your feedback.

image credit: eyehook.com, CC BY 2.5, via Wikimedia Commons