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:
- Reading your OpenAPI Document (either from a URL or local file)
- Generating TypeScript code that represents your API endpoints and types
- Converting these HTTP endpoints into GraphQL queries and mutations
- 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
- macOS and Linux
- Windows
Simply run the installer script in your terminal:
curl -L https://graphql-engine-cdn.hasura.io/ddn/cli/v4/get.sh | bash
Currently, the CLI does not support installation on ARM-based Linux systems.
- 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 theddn
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
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
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
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).
You can configure the OpenAPI Connector using supported environment variables.
Step 4. Introspect your OpenAPI Document
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.
ddn connector show-resources my_openapi
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
ddn commands 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.
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
ddn supergraph build local
The build is stored as a set of JSON files in engine/build
.
Step 7. Start your local services
ddn run docker-start
Your terminal will be taken over by logs for the different services.
Step 8. Run your first query
ddn console --local
query MyQuery {
getStoreGetOrderById(orderId: 10) {
complete
id
petId
quantity
shipDate
status
}
}
{
"data": {
"getStoreGetOrderById": {
"complete": true,
"id": 10,
"petId": 198772,
"quantity": 7,
"shipDate": "2025-03-04T08:23:30.139+00:00",
"status": "approved"
}
}
}
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
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
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
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
ddn supergraph build local
Step 10.5 Restart your services
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.