Créer un profil API personnalisé

Dans ce document, deux cas de création d'API seront abordés en fonction de leur niveau de difficulté, c'est-à-dire, de la manière dont les attributs sont imbriqués.

Pour le cas simple, les données relatives aux pays de l'API REST Countries seront utilisées, car l'arborescence est facile à comprendre et simple (c'est-à-dire que les attributs sont au niveau de la racine) pour construire et consolider votre base de connaissances.
Pour le cas avancé, les données relatives au change de devises étrangères (ForEX) de l'API Alphavantage seront utilisées pour découvrir ce qui est impliqué lorsque les attributs ne sont pas au niveau de la racine.

Étapes et informations communes

Ouvrez un éditeur de texte tel que Notepad et copiez-collez les lignes suivantes dans votre document :

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
<api:info xmlns:other="http://apiscript.com/ns?v1" title="A Title" desc="A Description">

Pour les valeurs title et desc, saisissez un titre et une description (de préférence en rapport avec les informations que vous souhaitez récupérer de l'API).
Enregistrez votre document en tant que fichier .rsd.

Important
La valeur de l'attribut title que vous entrez dans la balise <api:info> doit être identique au nom du fichier lors de l'enregistrement du fichier. Cette valeur est utilisée pour définir le nom de la table et constitue l'identifiant unique de l'API Web lors de l'ajout d'une table pour une extraction.

Exemple

Allez à la section documentation du fournisseur API. Dans le cas présent, il s'agit de l'API REST Countries.
Copiez l'adresse URI qui contient les données qui vous intéressent. Dans cet exemple, All Data (https://restcountries.com/v3.1/all) est choisie pour que toutes les données puissent être récupérées.
Dans Postman, cliquez sur le + à côté de l'onglet Overview pour créer une nouvelle requête.
Dans le champ GET , collez l'adresse URI et cliquez sur Send.
Comme vous pouvez le voir sur la capture d'écran ci-dessous, les attributs sont accessibles directement à partir de la racine, c'est-à-dire qu'il n'y a pas de nom d'élément avant le signe "{".
De retour à votre Notepad, ajoutez la ligne suivante pour créer les colonnes du tableau.
```
<attr name="X"               		xs:type="X"  	readonly="true"     other:xPath="X"/>
```
Pour faciliter la définition des valeurs, placez Postman sur l'un des côtés de votre écran et le Notepad sur l'autre côté.

Remplacez les valeurs X comme suit :

attr name="X"	Remplacez le "X" par un nom (de préférence) lié aux données qui seront récupérées dans la section other:xPath. Dans cet exemple, il s'agit de name (nom), capital (capitale), region (région), etc.
xs:type="X"	Remplacez le "X" par le type de données des attributs listés dans l'API. Dans cet exemple, il s'agirait de string si name (nom) ou tld (domaine de premier niveau) est choisi comme attribut ou integer si population ou area (surface) est choisi (voir Comprendre la structure des fichiers .rsd pour plus de détails concernant la liste des types de données).
readonly="true"	La propriété attribuée à cet attribut. Dans ce cas, cette propriété n'ajoute rien de spécial et est totalement facultative (par défaut, tous les attributs sont lus).
other:xPath="X"	Remplacer le "X" par le chemin où se situe l'attribut dans l'API. Dans cet exemple, comme les attributs sont situés au niveau de la racine, il suffit de répéter leur nom comme valeur pour xpath.
Propriété spécifique	Si vous avez besoin d'ajouter une propriété, ce sera à cet endroit que vous devrez l'insérer. Par exemple, si vous souhaitez attribuer une clé primaire à un attribut, vous pouvez ajouter key="true".

Dupliquez cette ligne pour ajouter autant d'attributs que vous le souhaitez et modifiez les valeurs en fonction de leur type de données, comme indiqué dans le tableau en dessus.
Une fois votre liste d'attributs terminée, fermez la liste en ajoutant la balise </api:info>.

Exemple

Copiez et collez cette ligne dans votre Notepad pour configurer les paramètres globaux.
```
<api:set attr="ContentType" value="application/json" />
```

Copiez et collez les lignes suivantes pour définir la méthode de script qui sera utilisée.

<api:script method="GET" >
    <api:set attr="method" value="GET" />
	<api:set attr="uri" value="X" />
    <api:set attr="RepeatElement" value="X" />

Remplacez les valeurs X comme suit :

api:set attr="uri" value="X"	Remplacez le "X" par la même adresse URI que vous avez collée dans Postman pour obtenir les données. Dans cet exemple, il s'agit de https://restcountries.com/v3.1/all.
api:set attr="RepeatElement" value="X"	Remplacer le "X" par un "/" puisque les données de cet exemple sont extraites du niveau racine, c'est-à-dire qu'il n'y a pas de nom d'attribut avant le signe "}". Voir Étapes spécifiques à un cas avancé s'il y a un élément répété (attribut) contenant des sous-attributs avec des espaces dans leurs noms ou s'il y a un tableau parmi les éléments dont vous voulez extraire les données.

Copiez et collez les lignes suivantes dans votre Notepad pour terminer la création de votre API personnalisée.
```
<api:call op="apisadoExecuteJSONGet">
      <api:push/>
    </api:call>
  </api:script>
 </api:script>
```
Exemple

Une fois le fichier .rsd complété :
1. Suivez la procédure décrite dans Paramètres pour Custom API pour créer et configurer une nouvelle connexion.
2. Suivez la procédure décrite dans Ajouter une extraction et Configurer le panneau d'extraction pour définir l'extraction.
3. Suivez la procédure décrite dans Lancer une extraction pour récupérer les données.

Étapes spécifiques à un cas avancé

Pour cette section, nous utilisons les données relatives au change de devises étrangères (ForEX) de l'API Alphavantage car les attributs ne sont pas au niveau de la racine.

Cette section est composée de deux exemples : le premier concerne la récupération de données à partir d'un RepeatElement qui n'est pas au niveau de la racine et le second concerne la récupération de données lorsque le RepeatElement est une variable.

Premier exemple

Répétez les étapes décrites dans Étapes et informations communes jusqu'à l'étape 7.

Comme vous pouvez le voir sur la capture d'écran ci-dessous, les attributs ne sont pas accessibles directement à partir de la racine, c'est-à-dire qu'il y a un nom d'élément avant le signe "{". Dans ce cas, le nom de l'élément est Realtime Currency Exchange Rate.
Suivez les étapes décrites dans Étapes et informations communes partir de l'étape 9 jusqu'à la fin pour créer votre profil API.
Pour la balise api:set attr="RepeatElement" value="X", remplacez X par la valeur placée avant le signe "{" dans le format suivant : /valeur/. Dans ce cas, il s'agit de Realtime Currency Exchange Rate.

Si les attributs comportent des caractères spéciaux tels qu'un trait de soulignement, des espaces ou des mots avec des accents, placez la valeur telle quelle entre des crochets [ ] dans la section other:xPath.

Dans Postman Devient Dans Notepad


other:xPath="[1. From_Currency Code]"/>
other:xPath="[2. From_Currency Name]"/>
other:xPath="[3. To_Currency Code]"/>
other:xPath="[4. To_Currency Name]"/>
other:xPath="[5. Exchange Rate]"/>
other:xPath="[6. Last Refreshed]"/>
other:xPath="[7. Time Zone]"/>

Exemple

Une fois le fichier .rsd complété :
1. Suivez la procédure décrite dans Paramètres pour Custom API pour créer et configurer une nouvelle connexion.
2. Suivez la procédure décrite dans Ajouter une extraction et Configurer le panneau d'extraction pour définir l'extraction.
3. Suivez la procédure décrite dans Lancer une extraction pour récupérer les données.

Deuxième exemple

Dans cette section, nous expliquons comment récupérer des données qui ne sont pas au niveau de la racine et lorsque le RepeatElement est une variable.

Répétez les étapes décrites dans Créer un profil API personnalisé jusqu'à l'étape 7.
Comme vous pouvez le voir sur la capture d'écran ci-dessous, les attributs ne sont pas accessibles directement à partir de la racine, c'est-à-dire qu'il y a un nom d'élément avant le signe "{", suivi de dates aléatoires agissant comme une variable, car elles sont incrémentées automatiquement. Dans ce cas, le nom de l'élément est Time Series FX (Daily).
Suivez les étapes décrites dans Étapes et informations communes partir de l'étape 9 jusqu'à la fin pour créer votre profil API.
Pour la balise api:set attr="RepeatElement" value="X", remplacez X par la valeur placée avant le signe "{" dans le format suivant : /valeur/. Dans ce cas, il s'agit de Time Series FX (Daily) suivi de "/%/" pour déclarer que les dates sont des variables.

Dans Postman Devient Dans Notepad


other:xPath="[1. open]"/>
other:xPath="[2. high]"/>
other:xPath="[3. low]"/>
other:xPath="[4. close]"/>

Exemple

Important

Si certains éléments sont présentés sous forme de tableau ou de liste comme dans l'exemple ci-dessous dans la section other:xPath, vous devrez déclarer chaque élément en les plaçant entre de crochets [ ] et en remplaçant leur valeur par des nombres commençant par 0.

Dans la documentation du fournisseur API	Devient	Dans Notepad
	=

Une fois le fichier .rsd complété :
1. Suivez la procédure décrite dans Paramètres pour Custom API pour créer et configurer une nouvelle connexion.
2. Suivez la procédure décrite dans Ajouter une extraction et Configurer le panneau d'extraction pour définir l'extraction.
3. Suivez la procédure décrite dans Lancer une extraction pour récupérer les données.