Skip to main content
Version: PromptQL

With API Endpoints

We can connect PromptQL to API endpoints to query them directly.

Sometimes bulk loading data from API services might be overkill. In such cases, connecting to API endpoints directly is useful or a convenient way to test your API integration.

However, if you expect to run into API rate limits, or need more flexible access to data that would require filtering data in ways that the API doesn't natively allow for, consider bulk loading the data instead.

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.

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.

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​

Instead of adding a connector that is backed by a persistent data store (like a database, or DuckDB), we'll add a lambda connector.

After creating your supergraph project with:

ddn supergraph init myproject --with-promptql

Load one of the following connectors:

  1. TypeScript + DuckDB: hasura/duckduckapi
  2. TypeScript with NodeJS runtime: hasura/nodejs
  3. Python: hasura/python

All of these connectors follow the same design, but for the purposes of this guide we'll follow the TypeScript guide.

Step 1. Initialize the connector​

Install the connector and say hello!

ddn connector init typescript -i

Step 2. Introspect the connector​

ddn connector introspect typescript
ddn commands list typescript

You should see a default hello command being AVAILABLE which means that it’s not yet added to the supergraph.

Step 3. Call an external API​

Open the app/connector/typescript/functions.ts file.

Replace the contents with the following:
/**
 * This is an API to say hello from httpbin for a given name
 * @readonly
 */
export async function helloFromHttpBin(name?: string): Promise<{ greeting?: string }> {
  const greeting = { greeting: name };

  const response = await fetch("https://httpbin.org/post", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ greeting: `Hello ${name}!` }),
  });

  const data: any = await response.json();
  return { greeting: data?.json?.greeting };
}

Step 4. Add the metadata​

ddn connector introspect typescript
ddn commands list typescript
ddn commands add typescript helloFromHttpBin

Step 5. Create and run a new build​

Create a new local build:
ddn supergraph build local
Run your services:
ddn run docker-start
In a new terminal tab, open the devlopment console:
ddn console --local

Head over to the PromptQL Playground and see if the AI assistant is able to call your API integration.

say hello from httpBin for everyone