Debian Codegraph @

doc/features/advanced/webapi.rst

raw
1 .. _ref-to-webapi:
2
3 Web API
4 =======
5
6 .. meta::
7 :description: How to use the DataLab Web API for HTTP/JSON integration
8 :keywords: DataLab, Web API, REST, HTTP, JSON, Jupyter, notebook, integration
9
10 The DataLab Web API provides a modern **HTTP/JSON interface** for external access
11 to the DataLab workspace. It is the recommended integration path for new projects,
12 especially for Jupyter notebooks and web-based tools.
13
14 .. note::
15
16 The Web API is available starting from DataLab 1.1. The required dependencies
17 (FastAPI, Uvicorn, Pydantic) are included in the standard DataLab installation.
18
19 Overview
20 --------
21
22 The Web API enables:
23
24 - **Jupyter notebook integration** via `DataLab-Kernel <https://github.com/DataLab-Platform/DataLab-Kernel>`_
25 - **WASM/Pyodide compatibility** (no XML-RPC dependency)
26 - **External tool integration** (any HTTP client)
27
28 Unlike the XML-RPC interface, the Web API:
29
30 - Uses **JSON** for metadata and **NPZ** for binary data (efficient large array transfer)
31 - Provides **bearer token authentication** for security
32 - Follows **REST conventions** with OpenAPI documentation
33 - Works in **browser environments** (WASM/Pyodide)
34
35 .. list-table:: Comparison with XML-RPC
36 :header-rows: 1
37
38 * - Feature
39 - XML-RPC
40 - Web API
41 * - Protocol
42 - XML
43 - JSON + Binary (NPZ)
44 * - WASM Support
45 - ❌
46 - ✅
47 * - Large Arrays
48 - Slow (base64)
49 - Fast (NPZ)
50 * - Authentication
51 - None
52 - Bearer Token
53 * - Standards
54 - XML-RPC
55 - REST + OpenAPI
56
57 Quick Start
58 -----------
59
60 Enabling the Web API
61 ^^^^^^^^^^^^^^^^^^^^
62
63 There are several ways to enable the Web API server:
64
65 1. **Via UI**: File → Web API → Start Web API Server
66 2. **Via environment variable**: Set ``DATALAB_WEBAPI_ENABLED=1`` before starting DataLab
67
68 When started, DataLab displays the server URL and authentication token in a dialog.
69 The status bar also shows the Web API port when the server is running.
70
71 The default port is **18080** (or the next available port if busy).
72
73 .. TODO: Add screenshot when available
74 .. figure:: /images/shots/webapi_started.png
75
76 Web API connection dialog showing URL and token
77
78 Auto-Discovery
79 ^^^^^^^^^^^^^^
80
81 DataLab-Kernel can automatically discover and connect to a running DataLab instance
82 without any manual configuration. When the Web API starts, DataLab writes connection
83 information to a file that DataLab-Kernel reads automatically.
84
85 **Just load the extension** — no environment variables or explicit connection needed:
86
87 .. code-block:: python
88
89 # In your notebook (JupyterLab, VS Code, etc.)
90 %load_ext datalab_kernel
91
92 # DataLab-Kernel automatically finds and connects to DataLab
93 workspace.list() # Already connected!
94
95 The auto-discovery mechanism tries the following methods in order:
96
97 1. **Environment variables** (``DATALAB_WORKSPACE_URL``, ``DATALAB_WORKSPACE_TOKEN``)
98 2. **Connection file** written by DataLab (native Python only)
99 3. **URL query parameters** (JupyterLite: ``?datalab_url=...&datalab_token=...``)
100 4. **Well-known port probing** (``http://127.0.0.1:18080``)
101
102 If discovery fails, DataLab-Kernel starts in standalone mode and you can connect
103 later using ``workspace.connect()``.
104
105 Manual Connection (Legacy)
106 ^^^^^^^^^^^^^^^^^^^^^^^^^^
107
108 If auto-discovery doesn't work (e.g., running on a different machine), you can
109 set environment variables before starting your notebook kernel:
110
111 .. code-block:: bash
112
113 export DATALAB_WORKSPACE_URL=http://127.0.0.1:18080
114 export DATALAB_WORKSPACE_TOKEN=<your-token>
115
116 Then in your notebook using DataLab-Kernel:
117
118 .. code-block:: python
119
120 from datalab_kernel import workspace
121
122 # List objects in DataLab
123 workspace.list()
124
125 # Retrieve an object
126 signal = workspace.get("my_signal")
127
128 # Add a processed result back to DataLab
129 workspace.add("processed", result)
130
131 API Reference
132 -------------
133
134 Base URL: ``http://127.0.0.1:<port>/api/v1``
135
136 Status Endpoint (No Auth Required)
137 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
138
139 .. list-table::
140 :header-rows: 1
141
142 * - Method
143 - Endpoint
144 - Description
145 * - GET
146 - ``/status``
147 - Server status and version information
148
149 Object Operations (Auth Required)
150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
151
152 All endpoints below require the ``Authorization: Bearer <token>`` header.
153
154 .. list-table::
155 :header-rows: 1
156
157 * - Method
158 - Endpoint
159 - Description
160 * - GET
161 - ``/objects``
162 - List all objects with metadata (JSON)
163 * - GET
164 - ``/objects/{name}``
165 - Get object metadata (JSON)
166 * - DELETE
167 - ``/objects/{name}``
168 - Delete an object
169 * - PATCH
170 - ``/objects/{name}/metadata``
171 - Update object metadata
172
173 Binary Data Transfer (Auth Required)
174 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
175
176 .. list-table::
177 :header-rows: 1
178
179 * - Method
180 - Endpoint
181 - Description
182 * - GET
183 - ``/objects/{name}/data``
184 - Download object as NPZ archive
185 * - PUT
186 - ``/objects/{name}/data``
187 - Upload object from NPZ archive
188
189 Data Format
190 -----------
191
192 Objects are transferred using NumPy's NPZ format for efficiency.
193
194 SignalObj NPZ Structure
195 ^^^^^^^^^^^^^^^^^^^^^^^
196
197 .. code-block:: text
198
199 my_signal.npz
200 ├── x.npy # X coordinates (float64)
201 ├── y.npy # Y data (float64)
202 ├── dx.npy # X uncertainties (optional)
203 ├── dy.npy # Y uncertainties (optional)
204 └── metadata.json # Labels, units, title
205
206 ImageObj NPZ Structure
207 ^^^^^^^^^^^^^^^^^^^^^^
208
209 .. code-block:: text
210
211 my_image.npz
212 ├── data.npy # 2D image array (preserves dtype)
213 └── metadata.json # Labels, units, coordinates (x0, y0, dx, dy)
214
215 Authentication
216 --------------
217
218 All API endpoints except ``/status`` require a bearer token:
219
220 .. code-block:: text
221
222 Authorization: Bearer <token>
223
224 The token is generated when the server starts and displayed in the connection dialog.
225
226 Environment Variables
227 ^^^^^^^^^^^^^^^^^^^^^
228
229 .. list-table::
230 :header-rows: 1
231
232 * - Variable
233 - Description
234 - Default
235 * - ``DATALAB_WEBAPI_HOST``
236 - Bind address
237 - ``127.0.0.1``
238 * - ``DATALAB_WEBAPI_PORT``
239 - Server port
240 - ``18080`` (or next available)
241 * - ``DATALAB_WEBAPI_TOKEN``
242 - Auth token
243 - Generated
244
245 Security Model
246 --------------
247
248 The Web API implements the following security measures:
249
250 1. **Localhost binding**: By default, the server only accepts connections from
251 the local machine (127.0.0.1).
252
253 2. **Token authentication**: Every request (except status) must include a valid
254 bearer token.
255
256 3. **Explicit opt-in**: Remote binding (0.0.0.0) requires explicit configuration.
257
258 Localhost Token Bypass
259 ^^^^^^^^^^^^^^^^^^^^^^
260
261 For simplified local development, you can disable token verification for localhost
262 connections in **Edit → Settings → Web API localhost bypass**.
263
264 When enabled, clients connecting from ``127.0.0.1`` do not need to provide a token.
265 This makes auto-discovery work seamlessly even when the connection file cannot be
266 read (e.g., in JupyterLite or sandboxed environments).
267
268 .. warning::
269
270 Only enable localhost bypass when you control all applications running on
271 your machine. Malicious local software could access your data without a token.
272
273 .. warning::
274
275 Exposing the API to the network allows anyone with the token to access your
276 data. Use with caution on trusted networks only.
277
278 Architecture
279 ------------
280
281 .. code-block:: text
282
283 ┌─────────────────────────────────────────┐
284 │ DataLab Main Window │
285 │ (Qt) │
286 ├─────────────────────────────────────────┤
287 │ WebApiController │
288 │ (Server Lifecycle) │
289 ├─────────────────────────────────────────┤
290 │ WorkspaceAdapter │
291 │ (Thread-safe access) │
292 ├─────────────────────────────────────────┤
293 │ FastAPI + Uvicorn │
294 │ (Separate thread) │
295 └─────────────────────────────────────────┘
296 ↑
297 │ HTTP/JSON
298 ↓
299 ┌─────────────────────────────────────────┐
300 │ DataLab-Kernel / Client │
301 └─────────────────────────────────────────┘
302
303 The Web API runs in a separate thread from the Qt GUI. The ``WorkspaceAdapter``
304 ensures thread-safe access to DataLab objects by marshalling calls to the main
305 thread using Qt's signal/slot mechanism.
306
307 Installation
308 ------------
309
310 The Web API dependencies are included in the standard DataLab installation:
311
312 - FastAPI (web framework)
313 - Uvicorn (ASGI server)
314 - Pydantic (data validation)
315
316 No additional installation steps are required.
317
318 Programmatic Control
319 --------------------
320
321 The Web API can also be started and controlled programmatically via the XML-RPC
322 interface, which is useful for automated workflows:
323
324 .. code-block:: python
325
326 from datalab.control.remote import RemoteClient
327
328 proxy = RemoteClient()
329 proxy.connect()
330
331 # Start the Web API server
332 info = proxy.start_webapi_server()
333 print(f"URL: {info['url']}")
334 print(f"Token: {info['token']}")
335
336 # Check status
337 status = proxy.get_webapi_status()
338 print(f"Running: {status['running']}")
339
340 # Stop the server
341 proxy.stop_webapi_server()
342
343 See Also
344 --------
345
346 - :ref:`ref-to-remote-control` for the XML-RPC interface (legacy)
347 - `DataLab-Kernel documentation <https://github.com/DataLab-Platform/DataLab-Kernel>`_ for Jupyter integration