dwn/api-overview.html at master

 <!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>API Overview - DWN Documentation</title>
     <link rel="stylesheet" href="css/style.css">
 </head>
 <body>
     <button class="mobile-menu-btn">Menu</button>
     <div class="layout">
         <aside class="sidebar">
             <div class="sidebar-header">
                 <h1>DWN</h1>
                 <span class="version">v2.0.0</span>
             </div>
             <div class="search-box">
                 <input type="text" class="search-input" placeholder="Search docs...">
             </div>
             <nav class="sidebar-nav">
                 <div class="nav-section">
                     <div class="nav-section-title">Getting Started</div>
                     <a href="index.html" class="nav-link">Introduction</a>
                     <a href="installation.html" class="nav-link">Installation</a>
                     <a href="quickstart.html" class="nav-link">Quick Start</a>
                 </div>
                 <div class="nav-section">
                     <div class="nav-section-title">User Guide</div>
                     <a href="features.html" class="nav-link">Features</a>
                     <a href="shortcuts.html" class="nav-link">Keyboard Shortcuts</a>
                     <a href="configuration.html" class="nav-link">Configuration</a>
                     <a href="layouts.html" class="nav-link">Layouts</a>
                     <a href="ai-features.html" class="nav-link">AI Integration</a>
                 </div>
                 <div class="nav-section">
                     <div class="nav-section-title">API Reference</div>
                     <a href="api-overview.html" class="nav-link active">API Overview</a>
                     <a href="api-reference.html" class="nav-link">API Reference</a>
                     <a href="api-examples.html" class="nav-link">API Examples</a>
                 </div>
                 <div class="nav-section">
                     <div class="nav-section-title">Advanced</div>
                     <a href="architecture.html" class="nav-link">Architecture</a>
                     <a href="abstraction-layer.html" class="nav-link">Abstraction Layer</a>
                     <a href="plugin-development.html" class="nav-link">Plugin Development</a>
                     <a href="building.html" class="nav-link">Building from Source</a>
                 </div>
             </nav>
         </aside>
         <main class="main-content">
             <div class="content">
                 <div class="page-header">
                     <h1>API Overview</h1>
                     <p class="lead">Introduction to DWN's WebSocket API</p>
                 </div>
                 <div class="toc">
                     <div class="toc-title">On this page</div>
                     <ul class="toc-list">
                         <li><a href="#introduction">Introduction</a></li>
                         <li><a href="#enabling">Enabling the API</a></li>
                         <li><a href="#connecting">Connecting</a></li>
                         <li><a href="#protocol">Protocol</a></li>
                         <li><a href="#quick-start">Quick Start</a></li>
                         <li><a href="#clients">Client Libraries</a></li>
                     </ul>
                 </div>
                 <h2 id="introduction">Introduction</h2>
                 <p>DWN provides a WebSocket API for full programmatic control of the window manager. This enables:</p>
                 <ul>
                     <li><strong>Test Automation</strong> - Automated UI testing and scripting</li>
                     <li><strong>Custom Hotkeys</strong> - Build custom keyboard shortcuts</li>
                     <li><strong>Remote Control</strong> - Control DWN from other machines or devices</li>
                     <li><strong>Integration</strong> - Connect DWN to other applications</li>
                     <li><strong>Accessibility</strong> - Build alternative input methods</li>
                 </ul>
                 <h2 id="enabling">Enabling the API</h2>
                 <p>The API is disabled by default. Enable it in <code>~/.config/dwn/config</code>:</p>
                 <div class="code-block">
                     <pre><code>[api]
 enabled = true
 port = 8777</code></pre>
                 </div>
                 <p>Restart DWN for changes to take effect.</p>
                 <div class="alert alert-info">
                     <strong>Security Note:</strong> The API listens on localhost only by default. Be cautious when exposing to network.
                 </div>
                 <h2 id="connecting">Connecting</h2>
                 <p>Connect via WebSocket to <code>ws://localhost:8777/ws</code> (or your configured port). The <code>/ws</code> path is required.</p>
                 <h3>Testing with wscat</h3>
                 <div class="code-block">
                     <pre><code># Install wscat
 npm install -g wscat
 # Connect to DWN
 wscat -c ws://localhost:8777/ws
 # Send a command
 > {"command": "get_clients"}
 < {"status": "ok", "clients": [...]}</code></pre>
                 </div>
                 <h3>Testing with websocat</h3>
                 <div class="code-block">
                     <pre><code># Install websocat
 cargo install websocat
 # Connect and send command
 echo '{"command": "get_clients"}' | websocat ws://localhost:8777/ws</code></pre>
                 </div>
                 <h2 id="protocol">Protocol</h2>
                 <h3>Request Format</h3>
                 <p>All requests are JSON objects with a <code>command</code> field:</p>
                 <div class="code-block">
                     <pre><code>{
     "command": "command_name",
     "param1": "value1",
     "param2": "value2"
 }</code></pre>
                 </div>
                 <h3>Response Format</h3>
                 <p>Responses include a <code>status</code> field:</p>
                 <div class="code-block">
                     <pre><code>// Success
 {
     "status": "ok",
     "data": {...}
 }
 // Error
 {
     "status": "error",
     "message": "Error description"
 }</code></pre>
                 </div>
                 <h3>Command Categories</h3>
                 <div class="table-container">
                     <table>
                         <thead>
                             <tr>
                                 <th>Category</th>
                                 <th>Commands</th>
                             </tr>
                         </thead>
                         <tbody>
                             <tr>
                                 <td>Clients</td>
                                 <td>get_clients, find_clients, get_focused_client, focus_client, focus_next, focus_prev, focus_master, close_client, kill_client, move_client, resize_client, minimize_client, restore_client, maximize_client, fullscreen_client, float_client, raise_client, lower_client, snap_client</td>
                             </tr>
                             <tr>
                                 <td>Workspaces</td>
                                 <td>get_workspaces, switch_workspace, switch_workspace_next, switch_workspace_prev, move_client_to_workspace</td>
                             </tr>
                             <tr>
                                 <td>Layout</td>
                                 <td>set_layout, cycle_layout, set_master_ratio, adjust_master_ratio, set_master_count, adjust_master_count</td>
                             </tr>
                             <tr>
                                 <td>Keyboard</td>
                                 <td>key_press, key_release, key_tap, key_type, get_keybindings</td>
                             </tr>
                             <tr>
                                 <td>Mouse</td>
                                 <td>mouse_move, mouse_move_relative, mouse_click, mouse_press, mouse_release, mouse_scroll, get_mouse_position</td>
                             </tr>
                             <tr>
                                 <td>Screenshot</td>
                                 <td>screenshot</td>
                             </tr>
                             <tr>
                                 <td>OCR</td>
                                 <td>ocr</td>
                             </tr>
                             <tr>
                                 <td>System</td>
                                 <td>get_status, get_screen_info, run_command, show_desktop, get_config, reload_config</td>
                             </tr>
                             <tr>
                                 <td>Notifications</td>
                                 <td>notify, close_notification, get_notifications</td>
                             </tr>
                             <tr>
                                 <td>System Tray</td>
                                 <td>get_battery_state, get_audio_state, set_audio_volume, toggle_audio_mute, get_wifi_state</td>
                             </tr>
                             <tr>
                                 <td>Panels</td>
                                 <td>get_panel_state, show_panel, hide_panel, toggle_panel</td>
                             </tr>
                             <tr>
                                 <td>AI</td>
                                 <td>ai_is_available, ai_command, exa_is_available, exa_search</td>
                             </tr>
                             <tr>
                                 <td>News</td>
                                 <td>get_news, news_next, news_prev, news_open</td>
                             </tr>
                             <tr>
                                 <td>Demo/Tutorial</td>
                                 <td>start_demo, stop_demo, get_demo_state, start_tutorial, stop_tutorial, get_tutorial_state</td>
                             </tr>
                             <tr>
                                 <td>Events</td>
                                 <td>subscribe, unsubscribe, list_events</td>
                             </tr>
                             <tr>
                                 <td>Fade Effects</td>
                                 <td>get_fade_settings, set_fade_speed, set_fade_intensity</td>
                             </tr>
                         </tbody>
                     </table>
                 </div>
                 <h2 id="quick-start">Quick Start</h2>
                 <h3>List Clients</h3>
                 <div class="code-block">
                     <pre><code>// Request
 {"command": "get_clients"}
 // Response
 {
     "status": "ok",
     "clients": [
         {
             "window": 12345678,
             "title": "Firefox",
             "class": "firefox",
             "workspace": 0,
             "x": 0, "y": 32,
             "width": 960, "height": 540,
             "focused": true,
             "floating": false,
             "fullscreen": false,
             "maximized": false,
             "minimized": false
         }
     ]
 }</code></pre>
                 </div>
                 <h3>Focus a Client</h3>
                 <div class="code-block">
                     <pre><code>{"command": "focus_client", "window": 12345678}</code></pre>
                 </div>
                 <h3>Switch Workspace</h3>
                 <div class="code-block">
                     <pre><code>{"command": "switch_workspace", "workspace": 2}</code></pre>
                 </div>
                 <h3>Type Text</h3>
                 <div class="code-block">
                     <pre><code>{"command": "key_type", "text": "Hello, World!"}</code></pre>
                 </div>
                 <h3>Take Screenshot</h3>
                 <div class="code-block">
                     <pre><code>// Request
 {"command": "screenshot", "mode": "fullscreen"}
 // Response
 {
     "status": "ok",
     "format": "png",
     "encoding": "base64",
     "width": 1920,
     "height": 1080,
     "data": "iVBORw0KGgo..."
 }</code></pre>
                 </div>
                 <h2 id="clients">Client Libraries</h2>
                 <h3>Python Client</h3>
                 <p>A Python client is included in the <code>examples/</code> directory:</p>
                 <div class="code-block">
                     <pre><code>from dwn_api_client import DWNClient
 # Connect
 client = DWNClient()
 client.connect()
 # List clients
 clients = client.get_clients()
 # Focus a client
 client.focus_client(clients[0]['window'])
 # Take screenshot
 result = client.screenshot('fullscreen')
 with open('screenshot.png', 'wb') as f:
     f.write(base64.b64decode(result['data']))
 # Disconnect
 client.disconnect()</code></pre>
                 </div>
                 <h3>JavaScript (Browser)</h3>
                 <div class="code-block">
                     <pre><code>const ws = new WebSocket('ws://localhost:8777/ws');
 ws.onopen = () => {
     ws.send(JSON.stringify({command: 'get_clients'}));
 };
 ws.onmessage = (event) => {
     const response = JSON.parse(event.data);
     console.log(response);
 };</code></pre>
                 </div>
                 <h3>Web Remote</h3>
                 <p>A web-based remote control interface is included at <code>examples/web_remote.html</code>. Open it in a browser to control DWN graphically.</p>
                 <h2>Next Steps</h2>
                 <ul>
                     <li><a href="api-reference.html">API Reference</a> - Complete command documentation</li>
                     <li><a href="api-examples.html">API Examples</a> - Code examples for common tasks</li>
                 </ul>
                 <footer>
                     <p>DWN Window Manager - retoor &lt;retoor@molodetz.nl&gt;</p>
                 </footer>
             </div>
         </main>
     </div>
     <script src="js/main.js"></script>
 </body>
 </html>