Get Started with Hasura DDN and HTTP APIs

Overview

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

• Set up a new Hasura DDN project
• Connect it to an existing HTTP API
• 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 from scratch. We'll connect to the {JSON} Placeholder API; 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 HTTP connector

In your project directory, run:

ddn connector init my_http -i

From the dropdown, select hasura/http (you can type to filter the list). The HTTP connector will not ask for any environment variables. Instead, you'll find a configuration file at app/connector/my_http/config.yaml.

This configuration file allows you to adjust the settings of your connector and determine which APIs are included; the files array expects an array of configuration files in either YAML or JSON format.

What types of configuration files can I use?

By default, the connector ships with the {JSON} Placeholder API's schema included. This is what we'll use in this guide.

However, you can use any OpenAPI 2 or 3 specification files. A list of common schemas can be found here.

Step 4. Introspect your API's schema

Next, use the CLI to introspect your API's schema:

ddn connector introspect my_http

After running this, you should see a representation of your database's schema in the app/connector/my_http/schema.output.json file; you can view this using cat or open the file in your editor.

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

ddn connector show-resources my_http

Step 5. Add your first command

The HTTP connector exposes each resource in the API's schema as a command.

Let's track a single command from the existing API:

ddn command add my_http getUsers

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 HTTP 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_USERS {
  getUsers {
    id
    name
  }
}

You'll get the following response:

{
  "data": {
    "getUsers": [
      {
        "id": 1,
        "name": "Leanne Graham"
      },
      {
        "id": 2,
        "name": "Ervin Howell"
      },
      {
        "id": 3,
        "name": "Clementine Bauch"
      },
      ...
    ]
  }
}

Step 9. Add another command

Let's add the command to query for posts:

ddn command add my_http getPosts

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 posts:

query GET_POSTS {
  getPosts {
    id
    userId
    title
    body
  }
}

You'll get a response like this:

{
  "data": {
    "getPosts": [
      {
        "id": 1,
        "userId": 1,
        "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
        "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
      },
      {
        "id": 2,
        "userId": 1,
        "title": "qui est esse",
        "body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
      },
      {
        "id": 3,
        "userId": 1,
        "title": "ea molestias quasi exercitationem repellat qui ipsa sit aut",
        "body": "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut"
      },
      ...
    ]
  }
}

Step 12. Create a relationship

In your DDN metadata, you can create relationships between resources in your API. Below, we'll define a relationship — with the assistance of the VS Code Extension — between users and posts.

Add the following to the end of the app/connector/my_http/metadata/getUsers.hml file:

---
kind: Relationship
version: v1
definition:
  name: posts
  sourceType: User
  target:
    command:
      name: GetPosts
  mapping:
    - source:
        fieldPath:
          - fieldName: id
      target:
        argument:
          argumentName: userId

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

Run the following query to return nested data about posts for each user:

query GET_USERS_AND_POSTS {
  getUsers {
    id
    name
    posts {
      id
      title
      body
    }
  }
}

You'll get a response like this:

{
  "data": {
    "getUsers": [
      {
        "id": 1,
        "name": "Leanne Graham",
        "posts": [
          {
            "id": 1,
            "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
            "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
          },
          {
            "id": 2,
            "title": "qui est esse",
            "body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
          },
          ...
        ]
      },
      ...
    ]
  }
}

create relationships to your own data

You can create relationships between resources in your connected HTTP API and data living in other data sources.

Step 13. Insert data

We can also track existing insert, update, and delete operations available via the API.

Let's track this createPost command:

ddn command add my_http createPost

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

Then, run the following mutation:

mutation INSERT_SINGLE_POST {
  createPost(body: { body: "This is a new post!", title: "New Post" }) {
    id
    title
  }
}

You'll get a response like this:

{
  "data": {
    "createPost": {
      "id": 101,
      "title": "New Post"
    }
  }
}

Next steps

Congratulations on completing your first Hasura DDN project with the HTTP connector! 🎉

Here's what you just accomplished:

• You started with a fresh project and connected it to the {JSON} Placeholder HTTP API.
• You set up metadata to represent your tables and relationships, 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.
• Finally, we looked at how to enable mutations and insert data using your new API.

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

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