dlt RESTClient vs REST API Source

dlt propose deux approches pour construire des pipelines d’API personnalisés. Les deux transforment les données d’API en tables d’entrepôt, mais représentent des compromis différents entre contrôle et vitesse de développement.

Les deux approches

RESTClient est l’option de bas niveau, impérative. On écrit du code Python qui instancie explicitement un client, gère les requêtes, traite les réponses et produit des données. Chaque comportement est explicite : on configure le paginator, on définit la stratégie d’authentification, et on définit comment les données circulent. Le client encapsule la bibliothèque requests de Python avec pagination et gestion de l’authentification intégrées.

REST API Source est l’option déclarative. On définit un dictionnaire Python décrivant la structure de l’API — endpoints, authentification, pagination, write dispositions — et dlt génère le pipeline à partir de cette description. Moins de code, développement plus rapide, mais le framework prend davantage de décisions à votre place.

La règle de décision

Commencez avec la REST API Source lorsque l’API suit des patterns courants : réponses JSON, pagination standard (offset, curseur, link header), et authentification correspondant à l’un des types intégrés (bearer token, clé API, OAuth2 client credentials). Pour une présentation étape par étape, voir dlt for AI-Assisted Pipeline Development — la REST API Source est particulièrement bien adaptée au développement assisté par IA car sa structure déclarative est prévisible pour les LLM.

Passez à RESTClient lorsque vous avez besoin de :

• Logique de pagination personnalisée — l’API utilise un schéma de pagination propriétaire ne correspondant à aucun paginator intégré
• Flux d’authentification complexes — rotation de refresh token, authentification multi-étapes, ou tout ce qui dépasse OAuth2 standard
• Contrôle précis sur le traitement requête/réponse — gestion personnalisée des erreurs, transformation des réponses avant production, ou logique au niveau requête que la configuration ne peut pas exprimer
• Migration progressive — encapsulation d’un script existant basé sur requests dans un pipeline dlt sans réécriture complète

Le choix n’est pas toujours évident dès le départ. Commencer avec la REST API Source et atteindre ses limites est une démarche tout à fait raisonnable. La configuration déclarative est facile à abandonner si RESTClient s’avère nécessaire.

Ce qu’ils partagent

Les deux approches produisent des resources dlt qui participent à la même mécanique de pipeline. Une fois qu’on dispose d’un @dlt.resource — qu’il soit construit avec le paginate() de RESTClient ou la configuration de la REST API Source — on bénéficie des mêmes avantages : inférence automatique de schéma, gestion de l’évolution du schéma, contrôle de la write disposition, et support BigQuery (ou toute autre destination).

# Les deux aboutissent ici — même pipeline, même destination
pipeline = dlt.pipeline(destination="bigquery", dataset_name="api_data")
pipeline.run(source)

La configuration par resource — write_disposition, primary_key — est disponible dans les deux approches. Le chargement incrémental via le suivi par curseur l’est également. La différence réside dans la façon d’exprimer la logique d’extraction de l’API, pas dans ce que dlt fait avec les données par la suite.

Dénormalisation de la REST API Source

Une différence fonctionnelle notable : la REST API Source dénormalise automatiquement les données JSON imbriquées en tables enfants relationnelles, avec des clés référentielles vers la ligne parente. Avec RESTClient, les structures imbriquées transitent sous forme de JSON brut à moins de gérer l’aplatissement soi-même. Pour les API avec des réponses profondément imbriquées — courantes dans les plateformes marketing et les API CRM — cette dénormalisation automatique représente un véritable avantage de productivité pour la REST API Source.

Pour la plupart des nouvelles intégrations, la REST API Source est le bon point de départ. RESTClient est là pour les cas où davantage de contrôle est genuinement nécessaire.