DissChain WDDS Translator est un service web qui convertit une requête REST de l’application legacy WDDS 2.1 en une requête pour l’API RENOV où l’ordre des paramètres est agnostique. Cela veut dire que les paramètres ne doivent pas respecter un ordre spécifique.
La RENOV API renvoit un fichier en attachement (données et méta données venant d’un seul ensemble de données) dans le format JSON-Stat 2.0 au WDDS Translator. Ce dernier renvoit le contenu du fichier en une réponse JSON sans transformation de contenu à l’utilisateur final.
Le Service Web :
fournit les données dans le format JSON-stat 2.0 ;
support uniquemenet le protocole REST (REpresentation State Transfer) ;
fournit les réponses en anglais, français et allemand.
Le WDDS Translator remplace le service web legacy WDDS 2.1 web et permet une transition douce des applications de visualisation de Estat.B4.
Au final, les fonctionnalités de WDDS Translator seront intégrées dans la RENOV API qui le remplacera de manière transparente.
Structure de la requête REST
La structure pour construire une requête REST est une URL : {host_url}/{service}/{version}/{response_type}/{datasetCode}?{format}&{lang}&{filters}
Partie URL | Exemple | Commentaire |
|---|---|---|
Partie fixe | ||
{host_url}/ | Partie fixe de la requête (site web) | |
{service}/ | statistics/ | Partie fixe de la requête qui indique le service |
{version}/ | 1.0/ | Partie fixe de la requête qui indique la version |
Partie dynamique | ||
{response_type}/ | data/ | Seules les données statistiques sont actuellement retournées |
{datasetCode} | t2020_10 | Code unique qui identifie les données recherchée (soit un set de données ou une extraction prédéfinie) |
?{format} | ?format=JSON | Paramètre optionel |
&{lang} | &lang=FR | Paramètre optionel |
&{filters} | &time=2019 | Paramètres optionels |
Les paramètres définis dans la requête REST
Les paramètres Filters
Les paramètres Filters (ou filtres) définis dans l’URL sont optionnels. Toutes les dimensions présentes dans le produit de données peuvent être utilisées comme filtre.
Les filtres commencent après le point d’interrogation ("?") dans l’URL. Ils sont séparés par "&" s’il y en a plusieurs.
La structure d’un paramètre filtre : <CODE_DIMENSION>=<VALEUR>
CODE_DIMENSION : le code de la dimension utilisée pour filtrer les données
le code de dimension doit exister dans le produit de données
l’ordre des filtres ne doit pas correspondre à l’ordre des dimensions dans le produit de données
VALEUR: la valeur du filtre est la position dans la dimension, par exemple
time=2019
geo=FR
CODE_DIMENSION et VALEUR peuvent être écrits en minuscule ou en majuscules ; la casse n’a pas d’importance dans l’URL de la requête.
Les paramètres de temps (Time)
Les paramètres "time" et "time_period" sont acceptés dans l’URL. Les deux ciblent la dimension TIME_PERIOD.
D’autres paramètres de temps peuvent être utilisés :
untilTimePeriod – filtre jusqu’à la valeur “TIME_PERIOD” définie
sinceTimePeriod – filtre depuis la valeur “TIME_PERIOD” définie
lastTimePeriod – valeur numérique qui filtre en partant de la fin le nombre de dimensions TIME_PERIOD
Il n’est pas autorisé d’utiliser plus d’un paramètre de temps dans la même requête.
La seule exception est d’utiliser sinceTimePeriod et untilTimePeriod ensemble. Ceci aura pour résultat de filtrer les valeurs sur l’intervalle de temps défini entre les deux valeurs.
Les paramètres de format et de langue
La seule valeur pour le paramètre « format » est "JSON".
Le paramètre de langue (« lang » ) peut avoir une de ces trois valeurs : “EN”, “FR”, ou “DE”. Si le paramètre n’est pas défini, la valeur “EN” est prise par défaut.
Messages d’erreur envoyé en cas de requêtes invalides
Code Erreur | Status HTTP | Description |
|---|---|---|
Erreur client | ||
100 Pas de résultats | 400 Requête incorrecte | Les résultats de la requête est vide. |
100 Pas de résultats | 404 Non trouvé | La ressource demandée n’est pas disponible. |
110 Non autorisé | 401 Non autorisé | Utilisé quand l’authentification est nécessaire mais ayant échouée ou n’ayant pas encore été fournie. Les erreurs ECAS peuvent être :
|
140 Erreur de syntaxe | 400 Requête incorrecte | La requête est invalide. |
140 Erreur de syntaxe | 404 Non trouvé | La ressource demandée ne fait pas partie des méthodes supportées. Ressources non supportées :
|
150 Erreur de sémantique | 400 Requête incorrecte | La requête est correcte au niveau syntaxique mais échoue à cause d’une validation sémantique ou un règle métier. |
Erreur serveur | ||
500 Erreur interne du serveur | 401 Non autorisé | La ressource demandée existe mais n’est pas disponible pour le moment. |
500 Erreur interne du serveur | 500 Erreur interne du serveur | Le service web devrait renvoyer cette erreur quand aucun autre code d’erreur est capable de mieux décrire la cause de l’échec du service à fournir une réponse correcte. Également utilise dans le cas où la requête ne respecte pas la définition du XSD. |
Réponse asynchrone dans le cas de grandes extractions
Quand l’API reçoit une requête de WDDS Translator, elle détermine si la réponse peut être faite de manière synchrone ou asynchrone.
Dans le cas d’une réponse asynchrone, WDDS Translator renvoit la réponse suivante en JSON :
{"warning":{"status":413, "label":"ASYNCHRONOUS_RESPONSE. Your request will be treated asynchronously. Please try again later."}}
WDDS ne notifie pas l’utilisateur quand le fichier est prêt, la requête doit être faite une nouvelle fois pour vérifier l’état.