# Web API (API Web)

Les données de grande qualité sont une partie essentielle de nombreuses applications construites aujourd'hui et le composant Web API permet à ces applications de récupérer des données à partir de n'importe quelle API (interface de programmation d'applications) public ou privé sur le web. Pour les développeurs plus avancés qui ont un accès en écriture à une API privée, ce composant permet également de télécharger et de supprimer des données.

Pour savoir quelles API publiques sont disponibles, nous vous recommandons [cette liste tirée de la devise de Todd](https://github.com/toddmotto/public-apis)

## **Vue d'ensemble**

* [Pour commencer](#pour-commencer)
* [Définition des paramètres](#definition-des-parametres-de-recherche-et-des-en-tetes)
* [Récupérer et Formater](#obtenir-et-formater-analyser-les-donnees)
  * [API Weather](#exemple-1-ouvrir-lapi-de-la-carte-meteorologique)
  * [API Google Maps](#exemple-2-api-de-la-matrice-de-distance-de-google-maps)

## **Pour commencer**

Pour la plupart des API publiques, vous devrez probablement d'abord créer un compte pour obtenir votre propre clé API unique. Cela permet généralement d'éviter que les particuliers fassent trop de demandes ou de faire payer les développeurs lorsqu'ils dépassent certaines limites de gratuité.

Une fois que vous avez la clé API, vous devez entrer l'URL unique dans le champ de propriété du composant API Web

| Propriété       | Description                                                                        |
| --------------- | ---------------------------------------------------------------------------------- |
| URL             | L'url de la requête web qui contient généralement une clé API                      |
| Query Parameter | Précise certains paramètres des données                                            |
| Headers         | Spécifie certaines méta-données, par exemple : noms d'utilisateur et mots de passe |

## **Définition des paramètres de recherche et des en-têtes**

Les paramètres de requête et les en-têtes peuvent être définis dans le concepteur ou dans l'éditeur de blocs. Dans l'exemple ci-dessous, vous pouvez ajouter n'importe quelle paire `property:value` (propriété:valeur) que vous souhaitez. Vous pouvez ajouter autant de paramètres à votre application que vous le souhaitez, mais chaque paramètre doit être ajouté à la fois.

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5Ly3eH8Wbz4QVTY%2F1.png?generation=1612663778580657\&alt=media)

Dans l'éditeur de blocs, il est possible d'utiliser le bloc `create object` pour ajouter simultanément plusieurs paires `property:value` (propriété:valeur).

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5Lz5m67EsLX1EKz%2F2.png?generation=1612663778580751\&alt=media)

En plus de créer vos propres objets, il est également possible d'utiliser JSON pour spécifier les paires property:value pour vos paramètres de requête ou vos en-têtes.

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5M-GNrZYM4q1yMP%2F3.png?generation=1612663778580677\&alt=media)

## **Obtenir et formater (analyser) les données**

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5M0eT65r-0ft2hi%2F4.png?generation=1612663778580952\&alt=media)

Ce bloc récupère et met en forme les données de l'API Open Weather Map

Pour récupérer les données d'une API, il suffit d'utiliser le bloc `Get`.

| Événement                          | Description                                                                                                                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get(`response`, `status`, `error`) | Exécute une requête HTTP GET en utilisant la propriété Url et récupère la `response`. Signale le `status` de la demande et si la demande n'aboutit pas, signale une `error` |

La plupart des API renvoient des données dans un format non utilisable par votre application. Nous allons donc prendre quelques instants pour vous présenter quelques exemples de formatage de données (également appelé "parsing") à l'aide de nos blocs [Object](https://docs.thunkable.com/objects)

### **Exemple 1 :** [**Ouvrir l'API de la carte météorologique**](https://openweathermap.org/current)

Vous en trouverez un exemple concret dans l'application [Office Weather & Traffic](../../../create-new-project/untitled-2#office-weather).

L'un des formats de sortie les plus courants pour les API est JSON, abréviation de Javascript Object Notation. L'API Open Weather Map renvoie un fichier JSON comme celui ci-dessous.

```
{
 "coord":{"lon":85.17,"lat":26.67},
 "weather" :[{"id":804,"main" :"Clouds","description" :"overcast clouds","icon" :"04n"}],
 "base" : "stations",
 "main":{
   "temp":298.312,
   "pression":1005.31,
   "humidity" : 94,
   "temp_min":298.312,
   "temp_max":298.312,
     "sea_level":1011.47,
     "grnd_level":1005.31},
 "wind":{"speed":2.96,"deg":79.5005},
 "clouds":{"tous":92},
 "dt":1533157826,
 "sys":{
     "message":0.0034,
     "country" : "IN",
     "sunrise":1533080664,
     "sunset":1533128790},
 "id":1273043,
 "name" : "Dhaka",
 "cod":200
}
```

#### **Convertir JSON en Object**

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5M1773c1LLwOGjh%2F5.png?generation=1612663778581156\&alt=media)

Si vous voulez simplement récupérer la température ("temp" : à la ligne 6), vous devrez d'abord convertir la réponse JSON en objets, une _entité_ comme une personne qui a des _propriétés_ pour les décrire comme intelligentes. Les objets peuvent être intégrés dans un autre objet.

Dans votre réponse JSON, les objets peuvent être trouvés entre les "guillemets" suivis d'un deux-points :. Les propriétés de l'objet suivent le deux-points : mais se trouvent à l'intérieur des {crochets}.

Dans l'exemple ci-dessus, `"coord" :` , `"weather" :`, `"base" :` et `"main" :` sont à la fois des objets et des propriétés de l'objet global puisqu'ils sont contenus dans les {crochets}.

#### **Obtenir la propriété d'un objet**

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5M2PkERKP0lj6tt%2F6.png?generation=1612663778580719\&alt=media)

Une fois que vous avez converti les JSON en objets, vous pouvez alors préciser les `objects` et les `property` qui vous intéressent. Pour obtenir la température (`"temp" :` à la ligne 6), on voudra trouver la propriété `temp` de l'objet principal qui est la propriété de l'objet global

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5M3SPm3Aa-pHafs%2F7.png?generation=1612663778580753\&alt=media)

### **Exemple 2 :** [**API de la matrice de distance de Google Maps**](https://developers.google.com/maps/documentation/distance-matrix/start)

Vous pouvez trouver un exemple de cette application dans l'exemple de l'application [Ride](https://community.thunkable.com/t/advanced-sample-app-ride-a-private-uber-like-app-made-on-thunkable/30646).

La sortie JSON de l'API de la matrice de distance de Google Maps semble similaire à l'API Open Weather Map, à une exception notable près : elle inclut des objets, des propriétés et des _listes_. Les listes sont des éléments délimités par des \[ crochets ].

```
{
 "destination_addresses" : ["Los Angeles, CA, USA" ],
 "origin_addresses" : San Francisco, CA, USA,
 "rows" : [
   {
    "elements" : [
     {
       "distance" : {
         "text" : "617 km",
         "value" : 616620
     },
       "duration" : {
         "text" : "5 hours 45 mins",
         "value" : 20680
      },
     "status" : "OK
     }
   ]
 }
],
 "status" : "OK
}
```

Si vous voulez récupérer la propriété `"text"` à la ligne 13, vous devrez faire :

* convertir le JSON en un objet
* sélectionner la propriété `"rows"` de l'objet
* sélectionnez le premier élément de la liste
* sélectionner la propriété `"elements"` de l'objet rows
* sélectionnez le premier élément de la liste
* sélectionner la propriété `"duration"` des éléments objet
* sélectionner la propriété `"text"` de l'objet durée

Vous pouvez voir l'exemple ci-dessous pour voir comment cela se présente en utilisant les blocs [Objet](https://docs.thunkable.com/objects) et [Liste](https://docs.thunkable.com/lists)

![](https://549775582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2Fthunkable%2F-MStw5ysO3HAWm_lueey%2F-MSuF5M4689X8HgIYUwp%2F8.png?generation=1612663778582204\&alt=media)

#### **Charger des données**

Le téléchargement et la suppression de données sont généralement réservés à une API privée dont vous ou votre organisation êtes propriétaire

| Événement                             | Description                                                                                                                                                                    |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Put (`response`, `status`, `error`)   | Exécute une requête HTTP PUT en utilisant la propriété Url et récupère la `response`. Rapporte le `status` de la demande et si la demande n'aboutit pas, signale une `error`   |
| Post (`response`, `status`, `error`)  | Effectue une requête HTTP POST en utilisant la propriété Url et récupère la `response`. Rapporte le `status` de la demande et si la demande n'aboutit pas, signale une `error` |
| Patch (`response`, `status`, `error`) | Exécute une requête HTTP PATCH en utilisant la propriété Url et récupère la `response`. Rapporte le `status` de la demande et si la demande n'aboutit pas, signale une `error` |

#### **Supprimer des données**

| Événement                              | Description                                                                                                                                                                              |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Delete (`response`, `status`, `error`) | Effectue une demande HTTP de SUPPRESSION en utilisant la propriété Url et récupère la `response`. Rapporte le `status` de la demande et si la demande n'aboutit pas, signale une `error` |

### **Voir aussi**

Vous pouvez également poster et recevoir des messages entre une page web et un [visualiseur web](../user-interface/web-viewer) en utilisant la fonction "Post Message". Pour en savoir plus à ce sujet, cliquez [ici](../../user-interface/web-viewer#post-message-receive-message).
