Get Started with Hasura DDN and Stripe

Overview

This tutorial takes about ten minutes to complete. You'll learn how to:

• Set up a new Hasura DDN project
• Connect it to a Stripe account
• Generate Hasura metadata
• Create a build
• Run your first query

Additionally, we'll familiarize you with the steps and workflows necessary to iterate on your API.

This tutorial assumes you're starting with an existing Stripe account which has some products and checkout sessions. Though, by the end, you'll be able to query any information stored in Stripe.

Hasura will never modify your source schema.

Prerequisites

Install the DDN CLI

macOS and Linux

Simply run the installer script in your terminal:

curl -L https://graphql-engine-cdn.hasura.io/ddn/cli/v4/get.sh | bash

ARM-based Linux Machines

Currently, the CLI does not support installation on ARM-based Linux systems.

Windows

• Download the latest DDN CLI installer for Windows.
• Run the DDN_CLI_Setup.exe installer file and follow the instructions. This will only take a minute.
• By default, the DDN CLI is installed under C:\Users\{Username}\AppData\Local\Programs\DDN_CLI
• The DDN CLI is added to your %PATH% environment variable so that you can use the ddn command from your terminal.

Install Docker

The Docker based workflow helps you iterate and develop locally without deploying any changes to Hasura DDN, making the development experience faster and your feedback loops shorter. You'll need Docker Compose v2.20 or later.

Validate the installation

You can verify that the DDN CLI is installed correctly by running:

ddn doctor

Tutorial

Step 1. Authenticate your CLI

Before you can create a new Hasura DDN project, you need to authenticate your CLI:

ddn auth login

This will launch a browser window prompting you to log in or sign up for Hasura DDN. After you log in, the CLI will acknowledge your login, giving you access to Hasura Cloud resources.

Step 2. Scaffold out a new local project

Next, create a new local project:

ddn supergraph init my-project && cd my-project

Once you move into this directory, you'll see your project scaffolded out for you. You can view the structure by either running ls in your terminal, or by opening the directory in your preferred editor.

Step 3. Initialize your Stripe connector

In your project directory, run:

ddn connector init my_stripe -i

From the dropdown, select hasura/stripe (you can type to filter the list), then hit enter to accept the default of all the options.

You'll be prompted for an environment variable:

Variable	Description	Example
STRIPE_BEARER_AUTH_TOKEN	A secret key for your account, retrievable from your API Keys dashboard in Stripe.	sk_<test|prod>_<unique_identifier>

Step 4. Introspect your Stripe account

Next, use the CLI to introspect your Stripe account:

ddn connector introspect my_stripe

After running this, you should see a representation of the Stripe API's schema in the app/metadata/my_stripe.hml file; you can view this using cat or open the file in your editor.

Under the hood, the Stripe connector utilizes the ndc-http connector via Stripe's OpenAPI spec. This ensures you can incorporate any resources available via Stripe's REST API into your supergraph.

Additionally, you can check which resources are available — and their status — at any point using the CLI:

ddn connector show-resources my_stripe

Step 5. Add your command

Let's start by tracking the GetProducts endpoint from Stripe's API:

ddn command add my_stripe GetProducts

Open the app/metadata directory and you'll find a newly-generated file: GetProducts.hml. The DDN CLI will use this Hasura Metadata Language file to represent the GetProducts endpoint from Stripe in your API as a command.

Step 6. Create a new build

To create a local build, run:

ddn supergraph build local

The build is stored as a set of JSON files in engine/build.

Step 7. Start your local services

Start your local Hasura DDN Engine and Stripe connector:

ddn run docker-start

Your terminal will be taken over by logs for the different services.

Step 8. Run your first query

In a new terminal tab, open your local console:

ddn console --local

In the GraphiQL explorer of the console, write this query:

query GET_ALL_PRODUCTS {
  getProducts {
    data {
      id
      name
      description
    }
  }
}

You'll get a response listing all of your products. For example:

{
  "data": {
    "getProducts": {
      "data": [
        {
          "id": "3bef8a40-3c33-11ee-bb29-070df467ec94",
          "name": "Tee",
          "description": "A great t-shirt!"
        },
        {
          "id": "e0a70b16-65b6-11ed-8788-8fa2504d64a3",
          "name": "Sticker Sheet",
          "description": "Who doesn't love stickers??"
        },
        {
          "id": "a44eda7c-65b6-11ed-997b-53b5bdb7117e",
          "name": "Hasuras in The Cloud Tee",
          "description": "The cloud for your cloud."
        },
        {
          "id": "8aa93f86-65b6-11ed-901c-f320d4e17bb2",
          "name": "Dark Furry Logo Tee",
          "description": "Furry for furries."
        }
      ]
    }
  }
}

Step 9. Add another command

Add the GetCheckoutSessions command:

ddn command add my_stripe GetCheckoutSessions

In app/metadata you'll find a newly-generated file: GetCheckoutSessions.hml. This will be used to expose customer checkout sessions and their related information via your supergraph API.

Step 10. Rebuild your project

Next, create a new build:

ddn supergraph build local

Bring down the services by pressing CTRL+C and start them back up:

ddn run docker-start

Step 11. Query your new build

Head back to your console and query the GetCheckoutSessions endpoint:

query GET_CHECKOUT_SESSIONS {
  getCheckoutSessions {
    data {
      id
      amountTotal
      customerDetails {
        name
        email
      }
    }
  }
}

Because of the schema of Stripe's API, you'll see results like this, which contain nested information, such as customer details:

{
  "data": {
    "getCheckoutSessions": {
      "data": [
        {
          "id": "cs_test_<unique_identifier>",
          "amountTotal": 1000,
          "customerDetails": {
            "name": "Rob",
            "email": "[email protected]"
          }
        },
        {
          "id": "cs_test_<unique_identifier>",
          "amountTotal": 1000,
          "customerDetails": {
            "name": "Sandeep",
            "email": "[email protected]"
          }
        }
      ]
    }
  }
}

create relationships to your own data

You can create relationships between resources in your Stripe account and data living in other data sources.

As an example, you may have a PostgreSQL database with a users model exposed and which contains an email field. This field can be used to create a relationship between the users model and a CheckoutSession (or any other resource that utilizes a unique email) to return information across your sources in a single query.

Next steps

Congratulations on completing your first Hasura DDN project with Stripe! 🎉

Here's what you just accomplished:

• You started with a fresh project and connected it to an existing Stripe account.
• You set up metadata to represent the various endpoints on Stripe's API, which acts as the blueprint for your API.
• Then, you created a build — essentially compiling everything into a ready-to-use API — and successfully ran your first GraphQL queries to fetch data.
• Along the way, you learned how to iterate on your schema and refresh your metadata to reflect changes.

Now, you're equipped to connect and expose your data Stripe data to other data sources, empowering you to iterate and scale with confidence. Great work!

The Stripe connector also supports mutations; you can create, update, or delete products; create new checkout sessions; refund payments; etc.

Take a look at our Stripe docs to learn more about how to use Hasura DDN with Stripe. Or, if you're ready, get started with adding permissions to control access to your API.