API - Démarrage

L’API expose différents points de terminaison pour différents objectifs:

• CATALOGUE, qui est utilisé pour la découverte des données;

• STATISTICS, qui remplace le service Web JSON pour Eurostat;

• SDMX 2.1, qui sont utilisés pour les requêtes synchrones relatives aux métadonnées et aux données ;

• ASYNC, qui est utilisé pour l’obtention de données en mode asynchrone.

Point de terminaison CATALOGUE

Le point de terminaison CATALOGUE permet de faire de la découverte de données et constitue un accès programmatique aux catalogues de données. Le point de terminaison CATALOGUE est disponible uniquement via REST.

Points de terminaison Statistics

API Statistics est un service web de requête de données dont les paramètres ne doivent pas respecter un ordre spécifique comparé à l'API SDMX 2.1.

Le Service Web :

• fournit les données dans le format JSON-stat 2.0 ;

• support uniquement le protocole REST (REpresentation State Transfer) ;

• fournit les réponses en anglais, français ou allemand.

Points de terminaison SDMX 2.1

Les points de terminaison SDMX de l’API sont des accès programmatiques aux métadonnées et aux données, avec la possibilité de/d':

• Obtenir une liste complète des ensembles de données disponibles publiquement

• Obtenir la définition complète de la structure d’un ensemble de données spécifique

• Télécharger un ensemble de données dans sa totalité ou en partie. Les requêtes personnalisées pour les données sont supportées.

Le temps de calcul et d’élaboration de la réponse dépend de la requête:

• Une requête visant une petite partie d’un ensemble de données peut engendrer une réponse ne pesant que quelques kilobytes, laquelle peut être renvoyée en quelques secondes;

• Une requête concernant un ensemble de données complet peut renvoyer une réponse de l’ordre de plusieurs megabytes, et peut nécessiter plusieurs minutes avant de renvoyer le résultat escompté. Lorsque ce type de requête s’avère nécessaire, il peut être utile de faire appel aux requêtes ascynhrones (décrites ci-après).

Les points de terminaison pour les artefacts SDMX (voir les spécifications techniques SDMX 2.1.) sont mentionnés ci-dessous.

Ces points de terminaison sont également étendus afin de pouvoir retourner des artefacts dans des formats autres que le format SDMX 2.1:

• JSON-stat

• TSV

• SDMX-CSV

Points de terminaison ASYNC pour réception de réponses asynchrones

Objectif des points de terminaison ASYNC

Le point de terminaison ASYNC est un accès programmatique aux réponses asynchrones correspondant aux grandes requêtes de données

Pour les différents points de terminaison listés ci-dessous, les données peuvent être retournées en mode synchrone ou en mode asynchrone:

• Mode synchrone: les données sont retournées directement en réponse à la requête. C’est l’opération par défaut

• Mode asynchrone: les données ne sont pas directement retournées en réponse. Au lieu de cela, une clé est retournée en réponse, laquelle clé permet ensuite l’accès aux données de la réponse via le point de terminaison asynchrone, dès que ces données sont disponibles.

La décision relative au choix du mode de requête (synchrone ou asynchrone) est liée à des facteurs tels que la complexité de la requête et le volume de données (nombre d’enregistrements) devant être renvoyé.

Points de terminaison ASYNC

Comment implémenter les requêtes asynchrones ?

Le processus asynchrone de réception des données peut être résumé comme suit:

1. Etape 1. Un client soumet une requête vers un des points de terminaison suivants: CATALOGUE, SDMX 2.1. L’API renvoie une réponse indiquant un motif de livraison asynchrone, avec une clé unique.

2. Etape 2. Le client s’adresse au point de terminaison asynchrone à intervalles réguliers avec la clé unique, pour s’assurer de la disponibilité des données demandées

3. Etape 3. Dès que les données sont disponibles, le client reçoit les données attachées à la réponse renvoyée pour la clé unique

Exemple

Etape 1: Requête initiale

La requête initiale doit être envoyée à l’un des points de terminaison asynchrones mentionnés ci-dessus.

La réponse à cette requête est structurée comme suit:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <ns0:syncResponse xmlns:ns0="http://estat.ec.europa.eu/disschain/soap/extraction">
         <dataResponse>
            <queued>
               <id>98de05ea-540a-43d3-903b-7c9e14faf808</id>
               <status>SUBMITTED</status>
            </queued>
         </dataResponse>
      </ns0:syncResponse>
   </S:Body>
</S:Envelope>

Etape 2: Obtenir l’état actuel de la requête

Le statut d’une requête asynchrone peut prendre une des valeurs suivantes:

L’état actuel d’une requête donnée peut être obtenu:

• Via une requête REST:

  • URL de la requête: https://<api_base_uri>/1.0/async/status/<id>

  • Exemple d’URL de requête: https://ec.europa.eu/eurostat/api/dissemination/1.0/async/status/98de05ea-540a-43d3-903b-7c9e14faf808

• Via une requête SOAP:

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:asy="http://estat.ec.europa.eu/disschain/soap/asynchronous" xmlns:asy1="http://estat.ec.europa.eu/disschain/asynchronous">
     <soapenv:Header/>
     <soapenv:Body>
        <asy:async>
           <asy1:status>
              <asy1:key>98de05ea-540a-43d3-903b-7c9e14faf808</asy1:key>
           </asy1:status>
        </asy:async>
     </soapenv:Body>
  </soapenv:Envelope>

Cette requête peut fournir différents résultats, en fonction de l’état actuel de la requête:

• DATA_NOT_YET_AVAILABLE: Aussi longtemps que l’exécution de la requête n’est pas terminée, le résultat suivant sera renvoyé:

  <S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
     <env:Header/>
     <S:Body>
        <S:Fault>
           <faultcode>100</faultcode>
           <faultstring>DATA_NOT_YET_AVAILABLE: Requested data is not yet available for download. Check the status of your request.</faultstring>
        </S:Fault>
     </S:Body>
  </S:Envelope>

• AVAILABLE: La requête est terminée. Dans ce cas, le statut renvoyé sera AVAILABLE et le résultat suivant sera renvoyé:

  <S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
     <env:Header/>
     <S:Body>
        <ns0:asyncResponse xmlns:ns1="http://estat.ec.europa.eu/disschain/asynchronous" xmlns:ns0="http://estat.ec.europa.eu/disschain/soap/asynchronous">
           <ns1:status>
              <ns1:key>98de05ea-540a-43d3-903b-7c9e14faf808</ns1:key>
              <ns1:status>AVAILABLE</ns1:status>
           </ns1:status>
        </ns0:asyncResponse>
     </S:Body>
  </S:Envelope>

Etape 3: Récupérer les données

Lorsque les résultats sont indiqués comme AVAILABLE, il est possible de télécharger les données. Les données peuvent être obtenues:

• Via une requête REST:

  • URL de requête: https://<api_base_uri>/1.0/async/data/<id>

  • Exemple d’URL de requête: https://ec.europa.eu/eurostat/api/dissemination/1.0/async/data/98de05ea-540a-43d3-903b-7c9e14faf808

• Via une requête SOAP:

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:asy="http://estat.ec.europa.eu/disschain/soap/asynchronous" xmlns:asy1="http://estat.ec.europa.eu/disschain/asynchronous">
     <soapenv:Header/>
     <soapenv:Body>
        <asy:async>
           <asy1:data>
              <asy1:key>98de05ea-540a-43d3-903b-7c9e14faf808</asy1:key>
           </asy1:data>
        </asy:async>
     </soapenv:Body>
  </soapenv:Envelope>

Lorsque les résultats sont renvoyés, les données sont attachés à la réponse SOAP:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <ns0:asyncResponse xmlns:ns1="http://estat.ec.europa.eu/disschain/asynchronous" xmlns:ns0="http://estat.ec.europa.eu/disschain/soap/asynchronous">
         <ns1:data>
            <ns1:key>98de05ea-540a-43d3-903b-7c9e14faf808</ns1:key>
            <ns1:include href="cid:1568a7ca-792b-4730-bd81-a0a152eafd96"/>
         </ns1:data>
      </ns0:asyncResponse>
   </S:Body>
</S:Envelope>

Erreurs renvoyées

Données non encore prêtes

Aussi longtemps que les données ne sont pas prêtes, le résultat SOAP renvoyé sera:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <S:Fault>
         <faultcode>100</faultcode>
         <faultstring>DATA_NOT_YET_AVAILABLE: Requested data is not yet available for download. Check the status of your request.</faultstring>
      </S:Fault>
   </S:Body>
</S:Envelope>

Clé invalide

Si la clé fournie n’est pas valide, le résultat SOAP renvoyé sera:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <S:Fault>
         <faultcode>100</faultcode>
         <faultstring>UNKNOW_REQUEST: Unknown request.</faultstring>
      </S:Fault>
   </S:Body>
</S:Envelope>