API Web#

L’API Web DataLab fournit une interface moderne HTTP/JSON pour un accès externe à l’espace de travail DataLab. C’est la voie d’intégration recommandée pour les nouveaux projets, en particulier pour les notebooks Jupyter et les outils basés sur le web.

Note

L’API Web est disponible à partir de DataLab 1.1. Les dépendances requises (FastAPI, Uvicorn, Pydantic) sont incluses dans l’installation standard de DataLab.

Aperçu#

L’API Web permet :

  • Intégration de notebooks Jupyter via DataLab-Kernel

  • Compatibilité WASM/Pyodide (pas de dépendance XML-RPC)

  • Intégration d’outils externes (tout client HTTP)

Contrairement à l’interface XML-RPC, l’API Web :

  • Utilise JSON pour les métadonnées et NPZ pour les données binaires (transfert efficace de grands tableaux)

  • Fournit une authentification par jeton bearer pour la sécurité

  • Suit les conventions REST avec documentation OpenAPI

  • Fonctionne dans les environnements navigateur (WASM/Pyodide)

Comparaison avec XML-RPC#

Fonctionnalité

XML-RPC

API Web

Protocole

XML

JSON + Binaire (NPZ)

Support WASM

❌

✅

Grands tableaux

Lent (base64)

Rapide (NPZ)

Authentification

Aucune

Jeton Bearer

Standards

XML-RPC

REST + OpenAPI

Démarrage rapide#

Activer l’API Web#

Il existe plusieurs façons d’activer le serveur API Web :

  1. Via l’interface : Fichier → API Web → Démarrer le serveur API Web

  2. Via variable d’environnement : Définir DATALAB_WEBAPI_ENABLED=1 avant de démarrer DataLab

Au démarrage, DataLab affiche l’URL du serveur et le jeton d’authentification dans une boîte de dialogue. La barre d’état affiche également le port de l’API Web lorsque le serveur est en cours d’exécution.

Le port par défaut est 18080 (ou le prochain port disponible s’il est occupé).

Découverte automatique#

DataLab-Kernel peut automatiquement découvrir et se connecter à une instance DataLab en cours d’exécution sans aucune configuration manuelle. Lorsque l’API Web démarre, DataLab écrit les informations de connexion dans un fichier que DataLab-Kernel lit automatiquement.

Chargez simplement l’extension — aucune variable d’environnement ni connexion explicite requise :

# In your notebook (JupyterLab, VS Code, etc.)
%load_ext datalab_kernel

# DataLab-Kernel automatically finds and connects to DataLab
workspace.list()  # Already connected!

Le mécanisme de découverte automatique essaie les méthodes suivantes dans l’ordre :

  1. Variables d’environnement (DATALAB_WORKSPACE_URL, DATALAB_WORKSPACE_TOKEN)

  2. Fichier de connexion écrit par DataLab (Python natif uniquement)

  3. Paramètres d’URL (JupyterLite : ?datalab_url=...&datalab_token=...)

  4. Sondage du port bien connu (http://127.0.0.1:18080)

Si la découverte échoue, DataLab-Kernel démarre en mode autonome et vous pouvez vous connecter plus tard avec workspace.connect().

Connexion manuelle (historique)#

Si la découverte automatique ne fonctionne pas (par exemple, en cas d’exécution sur une machine différente), vous pouvez définir des variables d’environnement avant de démarrer le noyau de votre notebook :

export DATALAB_WORKSPACE_URL=http://127.0.0.1:18080
export DATALAB_WORKSPACE_TOKEN=<your-token>

Puis dans votre notebook utilisant DataLab-Kernel :

from datalab_kernel import workspace

# List objects in DataLab
workspace.list()

# Retrieve an object
signal = workspace.get("my_signal")

# Add a processed result back to DataLab
workspace.add("processed", result)

Référence de l’API#

URL de base : http://127.0.0.1:<port>/api/v1

Point d’accès Status (sans authentification)#

Méthode

Point d’accès

Description

GET

/status

État du serveur et informations de version

Opérations sur les objets (authentification requise)#

Tous les points d’accès ci-dessous nécessitent l’en-tête Authorization: Bearer <token>.

Méthode

Point d’accès

Description

GET

/objects

Lister tous les objets avec métadonnées (JSON)

GET

/objects/{name}

Obtenir les métadonnées d’un objet (JSON)

DELETE

/objects/{name}

Supprimer un objet

PATCH

/objects/{name}/metadata

Mettre à jour les métadonnées d’un objet

Transfert de données binaires (authentification requise)#

Méthode

Point d’accès

Description

GET

/objects/{name}/data

Télécharger l’objet sous forme d’archive NPZ

PUT

/objects/{name}/data

Envoyer un objet depuis une archive NPZ

Format des données#

Les objets sont transférés au format NPZ de NumPy pour plus d’efficacité.

Structure NPZ de SignalObj#

my_signal.npz
├── x.npy          # X coordinates (float64)
├── y.npy          # Y data (float64)
├── dx.npy         # X uncertainties (optional)
├── dy.npy         # Y uncertainties (optional)
└── metadata.json  # Labels, units, title

Structure NPZ de ImageObj#

my_image.npz
├── data.npy       # 2D image array (preserves dtype)
└── metadata.json  # Labels, units, coordinates (x0, y0, dx, dy)

Authentification#

Tous les points d’accès de l’API sauf /status nécessitent un jeton bearer :

Authorization: Bearer <token>

Le jeton est généré au démarrage du serveur et affiché dans la boîte de dialogue de connexion.

Variables d’environnement#

Variable

Description

Valeur par défaut

DATALAB_WEBAPI_HOST

Adresse de liaison

127.0.0.1

DATALAB_WEBAPI_PORT

Port du serveur

18080 (ou le suivant disponible)

DATALAB_WEBAPI_TOKEN

Jeton d’authentification

Généré

Modèle de sécurité#

L’API Web implémente les mesures de sécurité suivantes :

  1. Liaison localhost : Par défaut, le serveur n’accepte que les connexions provenant de la machine locale (127.0.0.1).

  2. Authentification par jeton : Chaque requête (sauf status) doit inclure un jeton bearer valide.

  3. Opt-in explicite : La liaison distante (0.0.0.0) nécessite une configuration explicite.

Contournement du jeton pour localhost#

Pour simplifier le développement local, vous pouvez désactiver la vérification du jeton pour les connexions localhost dans Édition → Paramètres → Contournement localhost de l’API Web.

Lorsque cette option est activée, les clients se connectant depuis 127.0.0.1 n’ont pas besoin de fournir de jeton. Cela permet à la découverte automatique de fonctionner de manière transparente même lorsque le fichier de connexion ne peut pas être lu (par exemple, dans JupyterLite ou les environnements sandboxés).

Avertissement

N’activez le contournement localhost que lorsque vous contrôlez toutes les applications s’exécutant sur votre machine. Un logiciel malveillant local pourrait accéder à vos données sans jeton.

Avertissement

Exposer l’API sur le réseau permet à quiconque possédant le jeton d’accéder à vos données. À utiliser avec précaution uniquement sur des réseaux de confiance.

Architecture#

┌─────────────────────────────────────────┐
│           DataLab Main Window           │
│                 (Qt)                    │
├─────────────────────────────────────────┤
│            WebApiController             │
│         (Server Lifecycle)              │
├─────────────────────────────────────────┤
│            WorkspaceAdapter             │
│         (Thread-safe access)            │
├─────────────────────────────────────────┤
│          FastAPI + Uvicorn              │
│         (Separate thread)               │
└─────────────────────────────────────────┘
                  ↑
                  │ HTTP/JSON
                  ↓
┌─────────────────────────────────────────┐
│        DataLab-Kernel / Client          │
└─────────────────────────────────────────┘

L’API Web s’exécute dans un thread séparé de l’interface Qt. Le WorkspaceAdapter assure un accès thread-safe aux objets DataLab en acheminant les appels vers le thread principal via le mécanisme signal/slot de Qt.

Installation#

Les dépendances de l’API Web sont incluses dans l’installation standard de DataLab :

  • FastAPI (framework web)

  • Uvicorn (serveur ASGI)

  • Pydantic (validation de données)

Aucune étape d’installation supplémentaire n’est nécessaire.

Contrôle programmatique#

L’API Web peut également être démarrée et contrôlée par programmation via l’interface XML-RPC, ce qui est utile pour les flux de travail automatisés :

from datalab.control.remote import RemoteClient

proxy = RemoteClient()
proxy.connect()

# Start the Web API server
info = proxy.start_webapi_server()
print(f"URL: {info['url']}")
print(f"Token: {info['token']}")

# Check status
status = proxy.get_webapi_status()
print(f"Running: {status['running']}")

# Stop the server
proxy.stop_webapi_server()

Voir aussi#