Utiliser l'API sur le back office
Une API (Application Programming Interface) est une interface de programation qui permet d'accéder aux données d'un portail.
La documentation des API est réalisée en suivant la spécification OpenAPI 3.0, qui permet une description claire et compréhensible au travers d’une interface interactive. La prise en main des API par les développeurs est ainsi plus rapide.
Les API sont utilisées via des requêtes pour, par exemple, mettre à jour des données, ou pour en filtrer sur des jeux de données pouvant contenir des millions de lignes.
La plupart du temps, les API sont utilisées par des développeurs.
Documentation de l'API
Chaque jeu de données possède sa propre API disponible sur la page d'édition du jeu de données du back-office.
Nous allons utiliser l'API globale de l'organisation qui se trouve dans la barre de navigation du back office.
Dans la section de la documentation de l’API vous pouvez utiliser l'API et obtenir les réponses à vos requêtes. La documentation peut être lue dans un visualisateur externe, tel que Postman, SwaggerHub ou Stoplight.
Nous allons utiliser l'API pour obtenir la syntaxe des requêtes à envoyer avec la commande curl.
Rendez-vous dans la documentation de l'API :
- Documentation
- Utiliser l’API
- Choix des types des requêtes
Dans notre exemple, nous allons créer un jeu de données à l'aide de notre clé d'API.
Choisissez la section Jeux de données dans les types de requêtes.
- Choix du type de requêtes
- Ajout d’un jeu de données (Post)
- Faire une requête
- Notre clé d’API
- Fichier que nous souhaitons importer
- Exécution de la requête
- Réponse de la requête
- Commande curl
Les étapes 1 à 6 nous permettent de tester l'envoi d'une requête.
Une fois que vous avez cliqué sur le bouton Execute, la réponse de l'API est visible à l'étape 7.
L'étape 8 nous permet de voir la syntaxe de la commande envoyée, comme si nous avions utilisé la commande curl.
Plusieurs exemples de commandes curl sont disponibles sur la page : Exemples API.
Clé d'API
Un clé d'API permet d'augmenter le taux de demandes de requêtes et son débit de téléchargement.
Un contributeur peut générer sa propre clé sur son espace personnel pour réaliser des tests sur son compte personnel, par exemple.
Si vous n'avez pas accès à votre compte personnel en tant que compte actif, demandez à l'administrateur de votre organisation une clé d'API.
Vous avez accès aux paramètres de votre compte sur la barre de navigation de Data Fair.
Cliquez sur les paramètres et rendez-vous dans la section Clé d'API.
Renseignez le nom de votre clé et choisissez la portée de la clé (jeux de données, applications, connecteurs aux catalogues ou récupération d'informations statistiques).
Lorsque votre clé est créée, copiez la valeur de la clé secrète.
C'est cette clé que vous utiliserez dans vos appels.
Pour savoir comment utiliser la clé, un exemple vous est fourni sur le bouton UTILISER que vous trouvez en haut à droite de votre fiche.
La valeur de votre clé doit être contenue dans le header x-apiKey pour que vous soyez authentifié lors de votre requête API.
Si vous souhaitez aller plus loin dans l'utilisation, n'hésitez pas à nous contacter.
Il est possible de mettre à jour des jeux de données incrémentaux à l'aide de l'API ou encore d'utiliser les tableaux des données pour avoir des exemples de requêtes d'API poussées avec des filtres.