La REST API Source est l’approche déclarative de dlt pour construire des pipelines d’API. Au lieu d’écrire du code Python qui gère explicitement les requêtes et la pagination, on passe un dictionnaire de configuration décrivant le fonctionnement de l’API, et dlt gère l’exécution. L’intégralité du pipeline — authentification, pagination, inférence de schéma, normalisation — s’exécute à partir de cette configuration.
Cette note couvre le contenu de cette configuration et ce que dlt en fait.
La structure de la configuration
Une configuration de REST API Source comporte deux clés de premier niveau : client et resources.
from dlt.sources.rest_api import rest_api_source
source = rest_api_source({ "client": { ... }, # config partagée : URL de base, auth, pagination "resources": [ ... ], # liste des endpoints à extraire})Le bloc client définit tout ce qui est partagé entre tous les endpoints. Le bloc resources définit chaque endpoint individuel. Cette séparation permet de configurer l’authentification et l’URL de base une seule fois — et non par endpoint.
Le bloc client
"client": { "base_url": "https://api.github.com/", "paginator": HeaderLinkPaginator(links_next_key="next"), "auth": { "type": "bearer", "token": dlt.secrets["sources.github.api_key"], },},base_url — L’URL racine. Les chemins d’endpoints dans le bloc resources sont ajoutés à la suite.
paginator — La stratégie de pagination qui s’applique à tous les endpoints sauf si surchargée au niveau du resource. Ici, HeaderLinkPaginator est utilisé car l’API GitHub retourne les liens de pagination dans l’en-tête de réponse Link. Il vaut la peine de le spécifier explicitement : si vous l’omettez, dlt tente de détecter automatiquement le paginator, et lorsqu’une seule page de résultats est retournée, cette détection peut avertir d’un paginator manquant.
auth — Configuration de l’authentification. Le champ type correspond aux classes d’authentification intégrées de dlt : "bearer", "api_key", "http_basic", "oauth2_client_credentials". Pour l’ensemble complet des options d’authentification, voir dlt Authentication Patterns. Les identifiants doivent toujours provenir de dlt.secrets — jamais codés en dur. Voir dlt Secrets Management.
Il est également possible de passer directement des instances de classes plutôt que des dictionnaires de configuration :
from dlt.sources.helpers.rest_client.paginators import HeaderLinkPaginatorfrom dlt.sources.helpers.rest_client.auth import BearerTokenAuth
"client": { "base_url": "https://api.github.com/", "paginator": HeaderLinkPaginator(links_next_key="next"), "auth": BearerTokenAuth(token=dlt.secrets["sources.github.api_key"]),},Les deux formes fonctionnent ; la forme dictionnaire est plus portable pour les configurations générées par IA.
Le bloc resources
Chaque entrée dans la liste resources définit un endpoint :
"resources": [ { "name": "orgs-pokeapi-repos", "endpoint": { "path": "orgs/PokeAPI/repos", }, },],name — Définit le nom du resource, qui devient le nom de la table de destination. dlt le normalise : orgs-pokeapi-repos devient orgs_pokeapi_repos dans la base de données.
endpoint.path — Ajouté à base_url. L’URL complète pour l’exemple ci-dessus devient https://api.github.com/orgs/PokeAPI/repos.
Les resources peuvent surcharger le paginator et l’authentification définis au niveau client, endpoint par endpoint. Un endpoint nécessitant un style de pagination différent ou des identifiants à portée limitée peut spécifier sa propre configuration sans affecter les autres.
Création du pipeline
L’objet source alimente un pipeline dlt standard :
pipeline = dlt.pipeline( pipeline_name="github_pipeline", destination="duckdb", dataset_name="github_data",)
load_info = pipeline.run(github_source.with_resources("orgs-pokeapi-repos"))with_resources() permet d’exécuter un sous-ensemble des resources dans la source — utile pour tester un endpoint avant de lancer l’extraction complète.
Ce qui se passe automatiquement
Lors de l’exécution du pipeline, plusieurs choses se produisent sans avoir été écrites explicitement :
Pagination — dlt suit chaque page jusqu’à ce que l’API signale qu’il n’y en a plus. Avec HeaderLinkPaginator, il lit l’en-tête Link après chaque réponse et continue jusqu’à ce qu’aucun lien rel="next" n’apparaisse.
Inférence de schéma — dlt analyse le JSON de la réponse, détecte les types de champs et crée le schéma de la table de destination à partir de ce qu’il trouve. Il n’est pas nécessaire d’écrire des instructions CREATE TABLE.
Normalisation JSON imbriqué — Si l’API retourne des objets ou des tableaux imbriqués, dlt les aplatit en tables relationnelles. Un endpoint de dépôts incluant un tableau topics produit deux tables : la table principale orgs_pokeapi_repos et une table enfant orgs_pokeapi_repos__topics. La table enfant possède une clé étrangère vers la ligne parente. C’est automatique — aucune configuration n’est nécessaire.
Tables de métadonnées — dlt crée trois tables système dans votre dataset :
_dlt_loads— une ligne par exécution de pipeline, avec statut et timing_dlt_pipeline_state— suivi d’état incrémental (voir dlt Incremental Loading)_dlt_version— métadonnées de version dlt
Évolution de schéma — Si l’API ajoute un nouveau champ après votre premier chargement, dlt détecte la nouvelle colonne et exécute automatiquement le ALTER TABLE nécessaire lors de la prochaine exécution.
Examen des résultats avec DuckDB
Lorsque la destination est DuckDB, le pipeline crée un fichier .duckdb dans le répertoire du projet. Pour l’inspecter :
duckdb github_pipeline.duckdbDans le CLI DuckDB :
-- Voir toutes les tables du datasetSHOW ALL TABLES;
-- Inspecter le schéma d'une table spécifiqueDESCRIBE github_data.orgs_pokeapi_repos;
-- Interroger les donnéesSELECT id, name, owner__url, stargazers_countFROM github_data.orgs_pokeapi_reposLIMIT 5;Remarquez le nom de colonne owner__url : les champs d’objet imbriqués sont aplatis avec des séparateurs double underscore. Un champ JSON owner.url devient owner__url dans la table aplatie. Cette convention est cohérente entre toutes les destinations dlt.
Ajout du chargement incrémental
Pour configurer le chargement incrémental sur un endpoint, ajoutez un bloc params avec un type incremental :
{ "name": "pokeapi_repos_commits", "endpoint": { "path": "/repos/PokeAPI/{resources.pokeapi_repos.name}/commits", "params": { "since": { "type": "incremental", "cursor_path": "commit.author.date", "initial_value": "2024-01-01T00:00:00Z" } } }}La clé since est le paramètre API que GitHub utilise pour filtrer les commits par date. cursor_path est un chemin en notation pointée vers le champ de timestamp dans le JSON de réponse. initial_value définit le point de départ pour la première exécution. Lors des exécutions suivantes, dlt remplace la valeur initiale par la valeur maximale du curseur de l’exécution précédente. Voir dlt Incremental Loading pour la mécanique complète du suivi d’état.
La partie {resources.pokeapi_repos.name} dans le chemin ci-dessus concerne les resources dépendantes — utiliser la sortie d’un endpoint pour configurer un autre. Voir dlt Dependent Resources pour le fonctionnement de ce mécanisme.
L’avantage déclaratif
Le dictionnaire de configuration est prévisible, sérialisable et facile à générer par programmation. C’est pourquoi la REST API Source se marie bien avec le développement assisté par IA : un LLM lisant la documentation d’une API peut produire le dictionnaire de configuration de manière fiable, alors que l’écriture de code RESTClient personnalisé nécessite davantage de raisonnement sur le flux de contrôle.
Pour les API avec une pagination non standard ou des flux d’authentification complexes, la REST API Source atteint ses limites et on bascule vers RESTClient. Mais pour la majorité des API REST — pagination standard, authentification par bearer token ou clé API, réponses JSON — l’approche déclarative permet d’atteindre la production plus rapidement.