Preview deployments: Transforming API development

We're excited to announce support for preview deployments for your APIs. Tools like Vercel, Netlify and Cloudflare pages introduced preview deployments for frontend frameworks where each deployment got a unique URL without affecting the production URL.

Hasura Data Delivery Network (DDN) is bringing a similar experience to the world of APIs, increasing developer productivity, enabling better collaboration and higher confidence in your deployments through zero downtime production deploys and rollbacks.

Why preview deployments matter

Traditionally, API development is slow, each code change requires full deployments, and testing in lower environments and rollouts to production environments are done very carefully. Even after doing a lot of testing in the lower environments, deployments can still break production, resulting in costly rollbacks, often ending up in downtime.

Preview deployments in the frontend space addressed this problem by creating isolated environments for every code change. This is typically done where the assets can be compiled down to static files and can be served on demand at a unique URL. Some teams have advanced CICD workflows for their backend services where they have been able to achieve similar functionality using Kubernetes and other cloud native tools.

Tools like Cloudflare Workers are bringing the same concept into the API world, but are limited only to the functions you write and not to the entire API. They let you deploy a commit from a branch or a pull request into your production (or other) environments without affecting the version that is live for your users. Each deployment gets a unique URL so that your team can test out the changes in a safe isolated way.

Preview deployments enable developers to get faster feedback loops by making debugging and testing easier and makes collaboration possible without having to use local tunnels or re-creating the whole environment on another user's machine. When testing is done and you've verified your deployment, it can be promoted to be the live version that your users would see.

How does it work?

Hasura DDN is powered by Hasura v3 GraphQL Engine, where we have rearchitected the popular Hasura v2 GraphQL Engine to separate out the build time from run time. This innovation enables us to create new "builds" or "deployments" for your GraphQL APIs without affecting the version that is currently running and serving traffic in production. Combining this with the serverless architecture, where each API's configuration is looked up only when a request is processed, we are able to provide preview deployments for each change of your GraphQL, without an additional cost overhead.

Preview deployments are available across all plans of Hasura DDN, including the DDN Free plan. On Hasura DDN, deployments are called "builds."

A build can be applied to the default URL or API endpoint that is available to a project on DDN. Builds can be applied to a URL any number of times to update the GraphQL API served by that URL.

Trying it out

Each build you create on your Hasura DDN project will create a unique URL that serves the GraphQL API for that particular version of metadata used.

Creating a build outputs a unique URL for the GraphQL API along with a Build version.

The URL is of the format https://project-name-<build-version>.ddn.hasura.app where the <build-version> is a unique identifier for each build that is created.

Navigating to the Console URL, will bring up GraphiQL and the Supergraph Explorer to try out this particular version of the API.

Console showing the GraphQL API unique for the build.

When you make a change to the metadata, say you want the root field app_album to be GetAlbums , the following metadata can be changed and a new build can be created.

Metadata change for renaming a root field.
Creating a new build.

Note: The new build resulted in a new build version and therefore a new GraphQL API.

The console will now show the new build along with a dropdown to select which build is currently active. We can switch across each build and try each one out without affecting the other API.

Applying a build

Each Hasura DDN project comes with a "Project API," which is a URL without the build version that can be used in your production code. A build can be "applied" to a project so that whenever you update the GraphQL API, your application code doesn't need to be updated with the new URL. The build that powers your project can change without changing the URL.

Applying a particular build with the CLI.

When you switch to the Project API, which doesn't have the build version, the Console highlights which build is currently powering this URL.

Console using the Project API instead of Build API.

CI/CD integration

Builds can be created from anywhere using Hasura DDN CLI. This can be integrated with your CI/CD workflow, where you can hook up the CLI to create a build for every commit on your Hasura project repo. We have a GitHub action in development to automate this workflow.

You can create preview deployments for Pull Requests and once they are merged to main, it can be applied to the Project API. The system is versatile enough so that more complex workflows can be built on top of this.

What's next?

As of now, the only possible "promotion" of a build is to switch it immediately with whatever is currently applied. In the coming weeks, we plan to release more features around preview deployments and builds. This includes support for various deployment strategies including canary, blue green and rolling updates.

Along with upcoming support for custom domains, these strategies will be useful for build customized deployment workflows that fits into your use cases.

Sign up on Hasura DDN to try out preview deployments today and let us know what you think.

16 Apr, 2024
Subscribe to stay up-to-date on all things Hasura. One newsletter, once a month.
Accelerate development and data access with radically reduced complexity.