Working with Sessions

Since APIs and plugins can be called on any running machine on a d3 session, it’s important to direct your API queries to the director of the session. This can be done in two ways - via service discovery or via API commands.

DNS-SD discovery

d3 provides a DNS-SD entry specifically for the purpose of identifying a director on the network:

_d3director._tcp.local.

The session can be determined by reading the TXT record. To discover the API server on that director, look for the DNS-SD entry from it’s API server, per the discovery mechanisms:

Once you have the API endpoint you can target API queries to the director as normal.

API query discovery

As an alternative to using DNS-SD, you can use the existing APIs which do not require the use of a DNS-SD server:

Checking Session Status

First, query the session status endpoint:

GET /api/session/status/session

const response = await fetch("http://localhost/api/session/status/session");
const data = await response.json();
console.log("Solo mode:", data.result.isRunningSolo);
if (data.result.director) {
  console.log("Director:", data.result.director.hostname);
}

import requests
response = requests.get("http://localhost/api/session/status/session")
data = response.json()
print(f"Solo mode: {data['result']['isRunningSolo']}")
if "director" in data["result"]:
  print(f"Director: {data['result']['director']['hostname']}")

Response when NOT in a session (Solo mode)

{
    "status": {
        "code": 0,
        "message": "",
        "details": []
    },
    "result": {
        "isRunningSolo": true,
        "isDirectorDedicated": false,
        "actors": [],
        "understudies": []
    }
}

Response when in a session with a director

{
    "status": {
        "code": 0,
        "message": "",
        "details": []
    },
    "result": {
        "isRunningSolo": false,
        "isDirectorDedicated": true,
        "director": {
            "uid": "NNNNNNNNNNNNNNNNNNNNNN",
            "name": "string",
            "hostname": "string",
            "type": "Designer",
            "guiMode": "OffWhenActor",
            "guiVisible": true
        },
        "actors": [],
        "understudies": []
    }
}

Working with a Director

When operating in a session (indicated by isRunningSolo: false), all subsequent API commands should be directed to the director’s hostname. From the example above, you would direct your API calls to:

http://string/api/...

Example workflow

Here’s a complete example showing how to check the session status and adjust your API calls accordingly:

async function getApiHost() {
  const response = await fetch("http://localhost/api/session/status/session");
  const data = await response.json();
  if (data.result.isRunningSolo) {
      console.log("Running in solo mode - using localhost");
      return "localhost";
  }
  const directorHostname = data.result.director.hostname;
  console.log(`Running in session mode - using director: ${directorHostname}`);
  return directorHostname;
}

async function makeApiCall(hostname, endpoint) {
  const url = `http://${hostname}/api/${endpoint}`;
  const response = await fetch(url);
  return await response.json();
}

// Usage
const host = await getApiHost();
const health = await makeApiCall(host, "session/status/health");
console.log(health);

import requests

def get_api_host():
  response = requests.get("http://localhost/api/session/status/session")
  data = response.json()
  if data["result"]["isRunningSolo"]:
      print("Running in solo mode - using localhost")
      return "localhost"
  director_hostname = data["result"]["director"]["hostname"]
  print(f"Running in session mode - using director: {director_hostname}")
  return director_hostname

def make_api_call(hostname, endpoint):
  url = f"http://{hostname}/api/{endpoint}"
  response = requests.get(url)
  return response.json()

# Usage
host = get_api_host()
health = make_api_call(host, "session/status/health")
print(health)

This pattern ensures your API calls are properly routed whether you’re running in solo mode or in a session with a director.

Search documentation