> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/projet-data-and-ia/datasets/utiliser-lapi-dataset.md).

# Utiliser l'API dataset

Chaque Dataset publié dans Cleyrop est exposé via une **API d’accès sécurisée.** Cela permet d’interroger, de filtrer ou de consommer les données depuis une application externe, un service interne, ou un script automatisé.

Une **documentation** complète du contenu et des paramètres de l’API est disponible :

* **URL** : https\://***\<votre\_domaine>***/data-serve/swagger-ui/index.html
* **Description** : Ce Swagger décrit les endpoints disponibles pour accéder aux datasets.

***

## Créer un Token d’accès

Pour utiliser l’API, vous devez générer un token d’authentification.

{% hint style="danger" %}
Ce token est **personnel et possède les mêmes permissions d’accès que votre compte** sur l'ensemble des datasets .
{% endhint %}

**Étapes de création**

1. Cliquez sur votre nom d’utilisateur en bas à gauche de la plateforme.
2. Sélectionnez **Mon profil**.
3. Cliquez sur **Créer un token**.
4. Indiquez un nom de token et une durée de validité.
   * Durée par défaut : 1 an
   * Le token hérite des droits de l’utilisateur qui le génère.

{% hint style="info" %}
La valeur du token **n’est visible qu’une seule foi**s lors de sa création. Conservez-la dans un endroit sécurisé (ex. gestionnaire de mots de passe).
{% endhint %}

### Révoquer un Token

Pour supprimer un token existant :

1. Accédez à la page Mon profil → Liste des tokens.
2. Cliquez sur l’icône 🗑️ à la fin de la ligne correspondant au token.
3. Saisissez supprimer pour confirmer la révocation.

Une fois révoqué, le token n’est plus utilisable pour accéder à l’API.

## Utiliser l’API du Dataset

L’API est accessible via l’URL suivante :

* https\://***\<votre\_domaine>***/data-serve/api/v1/datasets/

| votre\_domaine | Le domaine de votre plateforme Cleyrop (ex: cleyrop.entreprise.cleyrop.tech). |
| -------------- | ----------------------------------------------------------------------------- |
| techname       | L’ID unique du dataset à exposer (visible dans sa fiche Dataset).             |

Le token doit être passé dans le **header** de la requête HTTP, avec la clé TOKEN.

#### Routes disponibles

<table><thead><tr><th width="109.6689453125">Méthode</th><th width="346.2607421875">Route</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/data-serve/api/v1/datasets</td><td>Liste tous les datasets accessibles par le token.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets</td><td>Récupère le <strong>contenu</strong> d’un dataset par son ID.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/structured</td><td>Récupère un dataset avec une réponse JSON structurée.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/metadata</td><td>Récupère l'ensemble des <strong>métadonnées</strong> d'un dataset</td></tr><tr><td>POST</td><td>/data-serve/api/v1/datasets/sql/query</td><td>Exécute une requête SQL sur l’ensemble des datasets accessibles.</td></tr><tr><td>POST</td><td>/data-serve/api/v1/projects/{projectID}/datasets/sql/query</td><td>Exécute une <strong>requête SQL</strong> sur les datasets d’un projet spécifique.<br>La <strong>description des colonnes</strong> est visible dans les résultats</td></tr></tbody></table>

### Lister les datasets

L’API Cleyrop permet de lister disponibles pour un utilisateur (interne du catalogue, ceux autorisés dans les projets dont il est membre)

### Lire un dataset

**Exemple de requête CURL**

*Remplacez techname par l'identifiant unique de votre Dataset et le token par le vôtre.*

{% code title="dataset api call" %}

```bash
curl 'https://cleyrop.maplateforme.net/data-serve/api/v1/datasets/techname' \
     -H 'TOKEN: my_great_token_689371'
```

{% endcode %}

**Informations utiles :**

* Les données retournées dépendent des permissions du token (accès restreint ou complet).
* Après chaque utilisation, la date de dernière utilisation du token est mise à jour dans votre profil.
* Vous pouvez également utiliser l’API depuis Python, PowerBI ou tout outil compatible REST.

### Filtrer les données avec une requête SQL

L’API Cleyrop permet également d’exécuter une **requête SQL** directement dans l’appel pour filtrer les données retournées.

Cela permet d’interroger uniquement la portion utile d’un dataset sans devoir récupérer l’ensemble du contenu.

```bash
curl 'https://cleyrop.maplateforme.net/data-serve/api/v1/datasets/techname?query=SELECT%20*%20FROM%20dataset%20WHERE%20pays%3D%27France%27%20AND%20revenu%20%3E%205000' \
     -H 'TOKEN: my_great_token_689371'
```

💡 *Les caractères spéciaux doivent être encodés en URL* (ex. espaces → %20, guillemets → %27).

#### Recommandations

* La requête doit être une **instruction SQL** valide supportée par l’API (SELECT uniquement).
* Le mot-clé FROM dataset fait référence au dataset exposé par l’API.
* Vous pouvez combiner des conditions WHERE, AND, OR, LIMIT, ORDER BY…

***

## Bonnes pratiques

* Ne **partagez jamais** votre token publiquement (code, requêtes, screenshots).
* Préférez des **tokens dédiés par usage** (ex. un token par application cliente).
* Surveillez la date de dernière utilisation pour identifier les accès inactifs.
* Révoquez les tokens non utilisés depuis plus de 90 jours.