Structurez de la donnée
Dans le chapitre précédent, vous avez vu qu'une des clés de l'API REST était la représentation de la ressource (JSON, XML,etc.). Allons voir ce qui se cache derrière les termes JSON et XML.
Découvrez JSON
Il s’agit d’un format de fichier permettant de stocker les données de manière organisée et lisible. Il est utilisé pour représenter des structures de données et des objets simples dans un code qui repose sur un navigateur web. Les données sont présentées dans un format textuel constitué de paires "clé – valeur" .
Le code suivant est du code JSON :
{
"currentVersion":10.3,
"folders":
[
"Canvas",
"Demographics",
"Elevation",
"Ocean",
"Polar",
"Reference",
"Specialty",
"Utilities"
],
"services":
[
{
"name":"NatGeo_World_Map",
"type":"MapServer"
},
{
"name":"USA_Topo_Maps",
"type":"MapServer"
},
{
"name":"World_Imagery",
"type":"MapServer"
},
{
"name":"World_Physical_Map",
"type":"MapServer"
},{
"name":"World_Shaded_Relief",
"type":"MapServer"
},
{
"name":"World_Street_Map",
"type":"MapServer"
},
{
"name":"World_Terrain_Base",
"type":"MapServer"
},
{
"name":"World_Topo_Map",
"type":"MapServer"
}
]
}Sur ce code, vous pouvez voir :
les clés en vert avant les
:; ce sont toujours des chaînes de caractères ;les valeurs en jaune, de l'autre côté des
:; elles peuvent être de plusieurs types, des chaînes de caractères, mais aussi des nombres, des tableaux, des objets...
À l'instar de XML, JSON est indépendant des langages, et peut se combiner avec nombre de ces derniers, dont C++, Java, Python.
Les documents JSON sont relativement légers et leur traitement côté serveur web est donc rapide.
Intéressez-vous au XML
Le XML est un langage de balisage, il permet de décrire des informations pour facilement les communiquer entre plusieurs applications. Il est dit extensible car il permet de décrire d'autres langages qui dérivent du XML et qui auront leurs propres balises et règles.
Ce format de fichier est conçu pour transmettre des informations entre applications informatiques.
On utilise des balises pour délimiter les informations, par exemple :
<NOM>ARCGIS</NOM>
<CREATEUR>Jack Dangermond</CREATEUR>Comme vous le voyez, les balises
<NOM>ou<CREATEUR>permettent de délimiter les informations correspondant au nom et aucréateur.<NOM>annonce le début des informations concernant lenom.</NOM>annonce la fin des informations concernant le titre (notez le slash/).
JSON ou XML, lequel choisir pour l'API REST ?
Les 2 formats JSON et XML peuvent être utilisés pour recevoir des données d'un service web.
Vous avez la possibilité de traduire un besoin soit avec JSON, soit avec XML. Par exemple, dans ma société, j'emploie 3 personnes (John Doe, Arlette Smith et Jean Dupont).
Le code JSON correspondant est le suivant :
{
"employees":
[
{
"prenom":"John",
"nom":"Doe"
},
{
"prenom":"Arlette",
"nom":"Smith"
},
{
"prenom":"Jean",
"nom":"Dupont"
}
]
}Le code XML correspondant est le suivant :
<employees>
<employee>
<prenom>John</prenom> <nom>Doe</nom>
</employee>
<employee>
<prenom>Arlette</prenom> <nom>Smith</nom>
</employee>
<employee>
<prenom>Jean</prenom> <nom>Dupont</nom>
</employee>
</employees>Vous allez me dire, lequel choisir pour mon API REST ?
En effet, XML est plus difficile à analyser que JSON : il est nécessaire d'avoir un analyseur XML. Alors que JSON peut être analysé dans un objet JavaScript standard.
De plus, JSON est plus rapide car étant moins verbeux, son analyse est plus simple.
Transmettez l’information
Vous venez d'apprendre à distinguer le format d'échange XML et le format d'échange JSON. Vous allez maintenant voir comment le format d'échange JSON est transmis par l'API.
Transmettez des informations avec votre API REST entre 2 logiciels
Dans l'exemple précédent (société avec 3 employés), imaginons qu'il existe une API REST permettant de récupérer la liste des employés de la société via la fonction : GET http://masociete.com/employees/all.
Si un client exécute cette requête, le serveur enverra la réponse suivante au format JSON :
{
"employees":
[
{
"prenom":"John",
"nom":"Doe"
},
{
"prenom":"Arlette",
"nom":"Smith"
},
{
"prenom":"Jean",
"nom":"Dupont"
}
]
}L'information du serveur vers le client est transmise grâce au protocole HTTP et à travers un format d'échange, ici JSON car c'est le plus courant pour l'API REST.
Configurez votre URL pour transmettre les paramètres
Comment transmettre des paramètres du client au serveur ?
Eh bien, en utilisant l'URL !
3 symboles sont utilisés pour ajouter une chaîne de paramètres à une URL :
?concatène l'URL et la chaîne de paramètres ;&sépare les paramètres multiples ;=assigne une valeur à un paramètre.
Par exemple, l'URL suivante comporte les paramètres Bbox, BboxSR, Layers, layerDefs, etc.
http://sampleserver6.arcgisonline.com/arcgis/rest/services/Wildfire/MapServer/export?bbox=-1.2800616666100327E7%2C3803571.1214327915%2C-1.1144321686843704E7%2C5687408.222440326&bboxSR=&layers=1&layerDefs=&size=&imageSR=&historicMoment=&format=png&transparent=false&dpi=&time=&layerTimeOptions=&dynamicLayers=&gdbVersion=&mapScale=&rotation=&datumTransformations=&layerParameterValues=&mapRangeValues=&layerRangeValues=&f=html
Comme vous pouvez le constater, il n'existe pas de limite dans le nombre de paramètres.
Pour terminer ce chapitre, je vous propose une vidéo de démonstration pour reprendre les notions que nous avons abordées :
Vous avez brillamment terminé cette 1re partie ! Un quiz vous attend pour évaluer votre connaissance des API. Ensuite, on se retrouve dans la partie suivante pour apprendre à intégrer à vos projets des API existantes !
