Using the Dagger API with HTTP and GraphQL

The Dagger API is an HTTP API that uses GraphQL as its low-level language-agnostic framework. Therefore, it's possible to call the Dagger API using raw HTTP queries, from any language that supports GraphQL. GraphQL has a large and growing list of client implementations in over 20 languages.

:::note In practice, calling the API using HTTP or GraphQL is optional. Typically, you will instead use a custom Dagger function created with a type-safe Dagger SDK, or from the command line using the Dagger CLI. :::

Dagger creates a unique local API endpoint for GraphQL HTTP queries for every Dagger session. This API endpoint is served by the local host at the port specified by the DAGGER_SESSION_PORT environment variable, and can be directly read from the environment in your client code. For example, if DAGGER_SESSION_PORT is set to 12345, the API endpoint can be reached at http://127.0.0.1:$DAGGER_SESSION_PORT/query

:::warning Dagger protects the exposed API with an HTTP Basic authentication token which can be retrieved from the DAGGER_SESSION_TOKEN variable. Treat the DAGGER_SESSION_TOKEN value as you would any other sensitive credential. Store it securely and avoid passing it to, or over, insecure applications and networks. :::

Command-line HTTP clients

This example demonstrates how to connect to the Dagger API and run a simple workflow using curl:

echo '{"query":"{
  container {
    from(address:\"alpine:latest\") {
      file(path:\"/etc/os-release\") {
        contents
      }
    }
  }
}"}'|   dagger run sh -c 'curl -s \
    -u $DAGGER_SESSION_TOKEN: \
    -H "content-type:application/json" \
    -d @- \
    http://127.0.0.1:$DAGGER_SESSION_PORT/query'

Language-native HTTP clients

This example demonstrates how to connect to the Dagger API and run a simple workflow in the following languages:

• Rust, using the gql_client library (MIT License)
• PHP, using the php-graphql-client library (MIT License)

Create a new directory for the project and install the GraphQL client.

mkdir my-project
cd my-project
cargo init
cargo add [email protected]
cargo add [email protected]
cargo add [email protected] -F full
cargo add [email protected]

mkdir my-project
cd my-project
composer require gmostafa/php-graphql-client

Once the client library is installed, create a Dagger API client.

Add the following code to src/main.rs:

Create a new file named client.php and add the following code to it:

This code listing initializes the GraphQL client library and defines the Dagger workflow to be executed as a Dagger API query. The dagger run command takes care of initializing a new local instance (or reusing a running instance) of the Dagger Engine on the host system and executing a specified command against it.

Run the Dagger API client using the Dagger CLI as follows:

Here is an example of the output:

dagger 6.1.0-23-cloud-amd64 unknown Linux

Dagger CLI

The Dagger CLI offers a dagger query sub-command, which provides an easy way to send raw GraphQL queries to the Dagger API from the command line.

This example demonstrates how to build a Go application by cloning the canonical Git repository for Go and building the "Hello, world" example program from it by calling the Dagger API via dagger query.

Create a new shell script named build.sh and add the following code to it:

This script uses dagger query to send two GraphQL queries to the Dagger API. The first query returns a content-addressed identifier of the source code directory from the remote Git repository. This is interpolated into the second query, which initializes a new container, mounts the source code directory, compiles the source code, and writes the compiled binary back to the host filesystem.

Add the executable bit to the shell script and then run it by executing the commands below:

chmod +x ./build.sh
./build.sh

On completion, the built Go application will be available in the working directory on the host, as shown below:

tree
.
├── build.sh
└── dagger-builds-hello

1 directory, 2 files