Get Started with Hasura DDN and OpenAPI

Overview

The Hasura OpenAPI connector allows you to seamlessly integrate HTTP APIs defined in OpenAPI (formerly Swagger) specifications into your Hasura GraphQL API. This connector works by:

1. Reading your OpenAPI Document (either from a URL or local file)
2. Generating TypeScript code that represents your API endpoints and types
3. Converting these HTTP endpoints into GraphQL queries and mutations
4. Exposing them through Hasura's DDN's GraphQL API

This means you can:

• Connect to any REST API that provides an OpenAPI specification
• Transform REST endpoints into GraphQL operations automatically
• Combine these APIs with other data sources in your Hasura project
• Apply Hasura's permission system to control access to these endpoints

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

This tutorial assumes you're starting from scratch. We will use the Petstore API in this tutorial, but you can use any OpenAPI document.

Prerequisites

Install the DDN CLI

Minimum version requirements

To use this guide, ensure you've installed/updated your CLI to at least v2.28.0.

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 OpenAPI connector

In your project directory, run:

ddn connector init my_openapi -i

From the dropdown, start typing openapi and hit enter. Then, provide the following values:

NDC_OAS_DOCUMENT_URI

https://petstore3.swagger.io/api/v3/openapi.json

NDC_OAS_BASE_URL

https://petstore3.swagger.io/api/v3

For now, you can leave the rest of the values as blanks (or their defaults, if present).

Environment Variables

You can configure the OpenAPI Connector using supported environment variables.

Step 4. Introspect your OpenAPI Document

Next, use the CLI to introspect your OpenAPI Docuemnt:

ddn connector introspect my_openapi

Running this command results in the creation of a few files in app/connector/my_openapi. Let's break it down:

api.ts - This file is generated using the OpenAPI document and is a direct represntation of it in Typescript. It contains the generated TypeScript client for the OpenAPI document. It also contains all the types (schemas) that are defined in the OpenAPI document, alongwith all the API calls.

functions.ts - This file contains simple wrapper functions over the API calls that are defined in the api.ts file. These functions will be exposed as queries and mutations in your DDN GraphQL API.

tsconfig.json - This file is the TypeScript configuration file for the generated code.

package.json, package-lock.json - These files are generated to manage the dependencies of the generated code.

You will also the a representation of the functions defined in functions.ts file in the definition.schema field of the app/connector/metadata/my_openapi.hml file.

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

ddn connector show-resources my_openapi

Under the hood

The OpenAPI Connector internally makes use of the TypeScript Lambda Connector to expose the generated code as a GraphQL API.

Step 5. Add your API

Now, track an API from your OpenAPI Document as a command in your DDN metadata:

ddn command add my_openapi getStoreGetOrderById

Open the app/metadata directory and you'll find a newly-generated file: GetStoreGetOrderById.hml. The DDN CLI will use this Hasura Metadata Language file to represent the getStoreGetOrderById function from functions.ts file as command. This function in turn represents the GET :/store/order/{orderId} API in your OpenAPI Document.

Import all at once

You can import all the APIs from your OpenAPI Document as commands by running ddn command add my_openapi "*".

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 OpenAPI 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 MyQuery {
  getStoreGetOrderById(orderId: 10) {
    complete
    id
    petId
    quantity
    shipDate
    status
  }
}

You'll get a similar response to the following:

{
  "data": {
    "getStoreGetOrderById": {
      "complete": true,
      "id": 10,
      "petId": 198772,
      "quantity": 7,
      "shipDate": "2025-03-04T08:23:30.139+00:00",
      "status": "approved"
    }
  }
}

Petstore API considerations

The Petstore API is a public API and may have different data than what is shown here. Also, sometimes the API may not return data for certain IDs, or, the server may not be accepting requests at all. These will show as errors in the console.

Step 9. Iterate on your OpenAPI Document

If you have added new APIs to your OpenAPI Document, you can introspect it again to update your metadata. The OpenAPI connector looks at the NDC_OAS_FILE_OVERWRITE to determine whether it should overwrite the existing api.ts and functions.ts file or not. You'll need to set this to true in your project's .env file if you wish to get the new changes from your OpenAPI Document into the generated TypeScript files.

Step 9.1 Set the NDC_OAS_FILE_OVERWRITE env var to true

In your projects .env file, make sure the the APP_MY_OPENAPI_NDC_OAS_FILE_OVERWRITE variable is set to true.

Step 10. Refresh your metadata and rebuild your project

Making changes

The following steps are necessary each time you make changes to your functions.ts file. This includes adding, modifying, or deleting functions.

Step 10.1. Kill your services

Bring down the services by pressing CTRL+C in the terminal tab logging their activity.

Step 10.2. Re-introspect your data source

Run the introspection command again:

ddn connector introspect my_openapi

You'll notice that the api.ts and functions.ts files have been updated with the new APIs.

Step 10.3. Update your metadata

Add the new APIs as commands:

ddn command add my_openapi "*"

Open the app/metadata directory and you'll find a newly-generated files for the new APIs.

Step 10.4. Create a new build

Next, create a new build:

ddn supergraph build local

Step 10.5 Restart your services

Bring everything back up:

ddn run docker-start

Step 11. Query your new build

Your GraphQL API should now have the new APIs from your OpenAPI Document. You can query them in the console.

Next steps

Congratulations on completing your first Hasura DDN project with HTTP APIs using OpenAPI! 🎉

Here's what you just accomplished:

• You started with a fresh project and connected it to HTTP APIs using an OpenAPI Document.
• You set up metadata to represent your HTTP APIs, 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 and refresh your metadata to reflect changes.

Now, you're equipped to connect and expose any data with an OpenAPI spec, empowering you to iterate and scale with confidence. Great work!

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