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.

NOTE This feature is not yet included in the beta version. Another beta will be shared which supports this as soon as it passes QA.

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:

_d3api._http._tcp.local.

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

API query discovery

As an alsternative 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:

curl http://localhost/api/session/status/session

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 getSessionStatus() {
    const response = await fetch('http://localhost/api/session/status/session');
    const data = await response.json();
    return data;
}

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

// Usage example
async function example() {
    const sessionStatus = await getSessionStatus();
    
    if (sessionStatus.result.isRunningSolo) {
        console.log('Running in solo mode - use localhost');
        // Make API calls to localhost
        await makeApiCall('localhost', 'your/endpoint');
    } else {
        // Get director hostname
        const directorHostname = sessionStatus.result.director.hostname;
        console.log(`Running in session mode - use director: ${directorHostname}`);
        // Make API calls to director
        await makeApiCall(directorHostname, 'your/endpoint');
    }
}

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