Les URL et l'encodage URL

Qu'est-ce qu'une API Web (Application Programming Interface) ?

Historiquement, la notion d'API WEB est synonyme de “service web”. Une API ou Interface de Programmation Applicative, décrit les fonctionnalités d'un service Web et la manière dont il les fournit : les routines, les protocoles, les entrées, les sorties, …

Les API sont une des bases les plus utilisées par les entreprises du numérique pour intégrer leurs services.

Dans un contexte de développement, une API est généralement définie comme un jeu de requêtes ou de messages HTTP (Hypertext Transfer Protocol), associées à une définition de la structure et du contenu de la réponse.

Remarque 1 : vous voyez tous les jours des requêtes HTTP,
c'est ce qui est affiché en haut à gauche de votre navigateur, dans la barre d'adresse.

Remarque 2 :

Dans App Inventor, les requêtes HTTP sont principalement utilisées avec un composant webviewer (ou afficheur Web) qui correspond à une fenêtre de navigateur. Ce composant peut afficher les pages web au format html.
Un autre composant que l'on peut utiliser, est le composant web qui renvoie la réponse elle-même, sans l'interpréter. C'est plus difficile à utiliser, car c'est à vous d'écrire l'algorithme qui traite la réponse. Nous nous en servirons quand nous voudrons traiter le résultat de requêtes à des bases de données.
Enfin, quand la reqête renvoie une image(pixels) ou un fichier image, la requête HTTP peut être traitée comme si c'était une image ou un fichier local, par exemple comme image de fond d'un composant "cadre" ou "canvas".

Qu'est-ce qu'une URL et comment la construire ?

Une requête HTTP est un message envoyé sur le Web sous forme d'adresse Web ou d'une URL (Uniform Resource Locator) décrite ci-dessous.

Qu'est-ce qu'une URL

Une URL, ou une adresse web, est la référence à une ressource du Web qui précise sa localisation sur le réseau et un mécanisme pour récupéréer le résultat attendu de cette ressurce. Les URL font le plus souvent référence à des pages web (http), mais on les utilise aussi pour transférer des fichiers (ftp), envoyer des mails (mailto), accéder à des bases de données (JDBC), ou pour d'autres applications.

Dans l'exemple ci-dessous l'URL permet d'obtenir une carte centrée sur Paris (48.8632473,2.3280377) avec un zoom de 7. L'URL ou la requête http contient :

• le protocole (https//, ...),
• l'hôte à qui on envoie la requête (www.google.com),
• un chemin d'accès à la ressource (/maps/),
• et les paramètres de la requête : (@48.8632473,2.3280377,7z),

Ce qui donne la requête suivante: https://www.google.com/maps/@48.8632473,2.3280377,7z sur laquelle vous pouvez cliquer pour afficher la page web correspondante.

Paramètres de la requête

Comme illustré dans cet exemple, les paramètres qui précisent le résultat demandé font partie de l'URL. Ils sont indiqués après le nom de l'hote et le chemin. Leur forme est libre (le fournisseur de service la précise dans sa documentation), mais on retrouve des cas relativement classiques

• dans l'exemple ci-dessus, la latitude, la longitude et le facteur de zoom de la carte suivent "@".
  Dans l'exemple ci-dessus, après avoir cliqué sur l'URL et affiché la page, vous pouvez modifier manuellement l'URL dans la barre d'adresse : passez par exemple le zoom à 4 ou à 12.

• avec le serveur open street maps le format est différent, les apramètres sont séparés par des "/", à la manière d'un chemin d'accès et le zoom précède la latitude et la longitude https://www.openstreetmap.org/#map=7/48.8632473/2.3280377&layers=H

• La façon nominale de définir les paramètres dns une requête, est d'exprimer les paramètres
  • à la suite de l'hôte et du chemin d'accès, en commençant par un "?"
  • sous forme de couples "champ" = "valeur", (ou key=value) où le champ est le nom du paramètre effectuer
  • ces couples sont séparés par le caractère "&"

Les champs (paramètres) et les valeurs sont définis par chaque fournisseur de service dans la documentation de son API. Par exemple l'API des cartes statiques Google est définie à cette adresse : https://developers.google.com/maps/documentation/maps-static/intro

Remarque :

comme vous le voyez ici, Google demande une clef d'API - depuis mi 2018 - dans les paramètres. Depuis cette date le serveur ne renvoie plus (ou pas toujours) la réponse sans cette clef. Donc vous devrez en obtenir une, via Google ou votre enseignant. L'utilisation est généralement gratuite, la procédure fait référence à un moyen de paiement. dommage ...

Dans l'exemple donné par Google :

https://maps.googleapis.com/maps/api/staticmap?
center=Brooklyn+Bridge,New+York,NY
&zoom=13
&size=600x300
&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794
&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284

&key=YOUR_API_KEY

les champs ou paramètres sont : center, zoom, size, maptype, markers, markers, markers

• chaque champ correspond au début d'un couple "champ=valeur"
• ils commencent après le ‘?’ et sont séparés par ‘&’.
• De plus les blancs ont été remplacés par des ‘+’
  et les ‘|’ par ‘%7C’. Nous allons voir pourquoi ci-dessous (encodage URL).

La valeur de chaque marker est elle même constituée de plusieurs sous-champs

• color, label, et couple de coordonnées
• qui sont séparées par ‘|’ (convertis en %7C)
  &markers=color:blue|label:S|40.702147,-74.015794
• Là encore - pour les sous-champs - chaque fournisseur de service peut décider d'utiliser des règles et/ou des séparateurs différents.

Encodage URL

Dans une URL certains caractères ont un sens particulier: ce sont des "caractères réservés".
Par exemple, le carcatère "espace" joue un rôle de séparateur dans un message HTTP.On ne peut donc pas l'utiliser pour définir les champs ou paramètres, comme dans une adresse postale qui contient des blancs.
Ces caractères interdits ou “réservés” doivent être remplacés dans la aprtie qui précise la requête : c'est ce que l'on appelle "l'encodage URL". Les caractèrtes réservés sont remplacsé apr le caractère % suivi de leur valeur en hexadecimal (voir les tables ci-dessous). Ce remplacement est obligaatoire pour les “caractères réservés” et recommandé pour ceux qui ne sont ni dans la liste des caractères "réservés", ni dans la liste des caractères "autorisés".
Dans le cas du caractère "espace" (qui est très fréquent) on peut aussi le remplacer par ’+’.

Dans App Inventor, un bloc permet d'effectuer ce remplacement. C'est le bloc encoder uri qui se trouve dans le composant Web, dans la catégorie connectivité.

Liste des caractères dont la conversion est obligatoire, et des valeurs qui les remplace

 !   #   $   &   '   (   )   *   +   ,   /   :   ;   =   ?   @   [   ]		
%21 %23 %24 %26 %27 %28 %29 %2A %2B %2C %2F %3A %3B %3D %3F %40 %5B %5D		
                

Liste des caractères dont la conversion est recommandée, et des valeurs qui les remplacent

  Newline          space   "   %   -   .   <   >   \   ^   _   `   {   |   }   ~
%0A or %0D or %0A   %20   %22 %25 %2D %2E %3C %3E %5C %5E %5F %60 %7B %7C %7D %7E
                

Par exemple, (comme on l'a vu plus haut) il est recommandé de remplacer &markers=color:blue|label:x|37.78,-122.46|37.77,-122.46|37.78,-122.45
par &markers=color:blue%7C label:x%7C 37.78,-122.46%7C 37.77,-122.46%7C 37.78,-122.45

et il est obligatoire de remplacer center=Brooklyn Bridge,New York,NY
par center=Brooklyn+Bridge,New+York,NY
ou par Brooklyn%20Bridge,New%20York,NY

Composants associés dans App Inventor

• le composant "webViewer" ou "afficher Web" permet d'afficher les pages web, comme le fait un navigateur.
  Ce composant peut être utilisé de plusieurs manières ou avec différenst APIs.
  Nous en présenterons 2 :
  • l'affichage de cartes dynamiques à partir de services Web (solution 1)
  • l'affichage avec des tables de fusion (solution 3)
• Le composant "canvas" ou "cadre" ne peeut afficher que des images (fixes), mais si l'URL renvoie un fichier image, alors cet URL peut être utilisé exactement comme le nom de fichier d'une image locale ! Ce composant peut être utilisé avec plusieurs APIs, nous le verrons avec Google Maps et avec streetview qui renvoient des cartes ou images statiques (solution 4). Mais cette solution implique de deispsoer d'une clef d'API a demander via l'interface Google.

Exercices:

Vous allez utiliser le service Mapquest pour afficher des cartes dites "statiques", c'est à dire sous formes d'images fixes que vous pourrez ensuite réutiliser dans vos programmes.

L'URL suivante correspond à la carte affichée ici.
https://www.mapquestapi.com/staticmap/v5/map?
center=48.8,2.3 &zoom=5 &size=400,400 &locations=Paris &key=WSD7vBaBWKwG24PmAMgzvU1IpiKugAZQ

L'utilisation de ce service Web nécessite une clef d'API facile à créer et sans déclarer de moyen de paiement. (La clef ci-dessus ne sera plus valide au moment où vous ferez cet exercice). Une clef gratuite permet d'effectuer gratuitement jusqu'à 15 000 requêtes par mois, ce qui devrait largement vous suffire.

La documentation qui suit utilise Vous devez la remplacer par la votre à créer à l'adresse https://developer.mapquest.com/documentation/ puis en cliquant sur le bouton Sign-up.

Dans la liste des API proposées dans la page https://developer.mapquest.com/documentation/ vous allez sélectionner Static Map API puis Getting started with static maps.

Puis vous allez tester les différents exemples proposés en recopiant les URL dans la barre d'adresse d'un navigateur sur votre PC.Exercez-vous à modifier la valeur des paramètres.

Vous noterez :

• que les paramètres de la carte sont exprimés sous forme de couples " champ=valeur",
• que les espaces sont remplacés par des '+' (voir les adresses de géolocalisation),
• que les "sous-champs" sont séparés par des '||', ce qui est différent du choix effectué par Google illustré plus haut.

Quiz / auto contrôle:

à compléter ou supprimer