Les APIs REST

Introduction

De manière générale, les APIs (→ API : Application Program Interface) sont des services qui permettent aux développeurs d’applications de créer plus facilement des fonctionnalités complexes (Ex. framework Qt pour développer des applications graphique natives, module PHP PDO pour accéder aux bases de données…).

Dans le cas d’applications web, ces APIs sont mises à disposition :

soit par le navigateur (→ API du navigateur)
soit par des serveurs (→ API Web tierce).

Les APIs web sont souvent utilisées pour intégrer aux pages web des informations provenant d’autres sites.

Lorqu’on parle d'API Web, on évoque souvent les concepts/technologies suivants :

REST
JSON

Ces concepts/technologies vont être présentés ci-après en se basant sur l’utilisation de l'API Découpage Administratif (API Geo) link .

Cette API est décrite sur son site comme “une boîte-à-outils facile à prendre en main pour rendre vos applications et bases de données plus intelligentes, en termes de positionnement et de connaissance des territoires”. Grâce à elle, vous pouvez notamment rechercher des communes par nom, code postal ou coordonnées géographiques et obtenir de celles-ci un certain nombre d’informations telles que leurs populations, leurs codes postaux…

Son accès est gratuit et reste simple à mettre en œuvre vu le nombre limité de fonctionnalités qu’elle propose.

Architecture REST

De manière très simplifiée, l’architecture REST (REpresentational State Tranfert) va permettre d’accéder à une ressource sur internet à partir des méthodes proposées par le protocole HTTP (HyperText Transport Protocol).

Une de ces méthodes est la méthode GET. Celle-ci est par exemple utilisée lorsque que vous saisissez l’adresse suivante dans un navigateur :

https://geo.api.gouv.fr/communes?nom=L%27Isle-sur-la-Sorgue&fields=population&format=json

Les outils de développement de Firefox permettent de visualiser le type de méthode utilisée pour l’accès à une ressource Web :

Outre la méthode HTTP permettant d’y accéder, une ressource sur internet est également caractérisée par ce qu’on appelle son URL (→ URL : Uniform Resource Locator) ou, de manière plus générale, son URI (→ URI : Uniform Resource Identifier).

La différence entre URL et URI est qu’une URL va préciser l’endroit où se trouve la ressource alors que l'URI ne sert théoriquement qu’à l’identifier. Cependant, la plupart du temps, ces 2 termes sont utilisés de façon interchangeable.

L'URL donnée en exemple (→ https://geo.api.gouv.fr/communes?nom=L%27Isle-sur-la-Sorgue&fields=population&format=json ) est constituée de 2 parties :

Le début de l'URL (→ `https://geo.api.gouv.fr/communes) constitue le chemin d’accès à la ressource. Celui-ci est lui-même constitué de 3 parties :
1. le schéma (→ https) qui identifie le protocole utilisé pour accéder à la ressource internet. hhtps correspond au protocole HTTP sécurisé
2. le domaine (→ geo.api.gouv.fr) qui représente le nom ou l’adresse IP de la machine qui héberge la ressource
3. le chemin (→ /communes) qui indique ce qu’on peut assimiler au répertoire de la machine dans lequel se trouve la ressource.
La fin de l'URL (→ nom=L%27Isle-sur-la-Sorgue&fields=population&format=json`) constitue la requête. Celle-ci est séparée du début de l'URL par un point d’interrogation (→ ‘?’) et son contenu est généralement constitué de fragments de la forme “<clé>=<valeur>” séparés par des esperluettes (→ ‘&’ ).

Au sein d’une URL un certain nombre de caractères ont un sens particulier et ne peuvent être utilisés directement. Ainsi, une URL ne doit pas contenir d’espaces, d’apostrophes… Lorsqu’on est obligé d’utiliser ces caractères, on doit les encoder d’une manière particulière qui consiste à utiliser le symbole de pourcentage (→ ‘%’) suivi d’un nombre à 2 chiffres qui représente le code ASCII du caractère en question codé en hexadécimal.

Tableau 1. Caractères réservés dans les URLs et leurs encodages respectifs
! → %21	# → %23	$ → %24	& → %26	' → %27	( → %28
) → %29	* → %2A	+ → %2B	, → %2C	/ → %2F	: → %3A
; → %3B	= → %3D	? → %3F	@ → %40	[ → %5B	] → %5D

Dans l'URL exemple (→ https://geo.api.gouv.fr/communes?nom=L%27Isle-sur-la-Sorgue&fields=population&format=json), la requête spécifie pour la clé “nom” une valeur qui vaut normalement “L’Isle-sur-la-sorgue”. Or, l’apostrophe est un des caractères spéciaux qui possède un sens particulier. Celui-ci a donc été remplacé par le code %27 dans l’URL ( → …?nom=L%27Isle-sur-la-Sorgue&…).

La méthode GET n’est pas la seule qui permet d’accéder à une API Web de type REST. D’autres méthodes existent selon l’opération que l’on désire effectuer.

Méthode HTTP	Opération
POST	Création d’une ressource
GET	Lecture d’une ressource
PUT	Mise à jour/Remplacement d’une ressource
PATCH	Mise à jour/Modification d’une ressource
DELETE	Destruction d’une ressource

Méthode HTTP

Opération

POST

Création d’une ressource

GET

Lecture d’une ressource

PUT

Mise à jour/Remplacement d’une ressource

PATCH

Mise à jour/Modification d’une ressource

DELETE

Destruction d’une ressource

Le format JSON

JSON (→ JSON : JavaScript Object Notation) constitue un format qui permet de représenter sous forme de texte des informations structurées. Comme son nom l’indique, il a été créé au départ pour être utilisé avec Javascript mais son utilisation s’est répandue et il est désormais supporté par la majorité des langages utilisés dans le domaine du Web (PHP par exemple).

Ce format a supplanté le format XML qui était auparavant utilisé lors des échanges avec les services Web. Les APIs Web tierces utilisent donc très souvent ce format pour retourner les réponses aux requêtes émises par les navigateurs ou applications web.

Comme l’indique Wikipedia :

un document JSON ne comprend que deux types d’éléments structurels :

des ensembles de paires nom / valeur ;

des listes ordonnées de valeurs.

Ces mêmes éléments représentent trois types de données :

des objets ;

des tableaux ;

des valeurs génériques de type tableau, objet, booléen, nombre, chaîne ou null.

Ainsi, lorsqu’on s’adresse à l’API Web du site API Geo avec la requête https://geo.api.gouv.fr/communes?nom=L%27Isle-sur-la-sorgue&fields=code,codesPostaux,centre,population&format=json&geometry=centre pour obtenir des information sur l’Isle-sur-la-sorgue, celle-ci nous renvoie une réponse brute, qui, une fois reformatée, donne :

[
  {
    "code": "84054",
    "codesPostaux": [
      "84800"
    ],
    "centre": {
      "type": "Point",
      "coordinates": [
        5.0588,
        43.9191
      ]
    },
    "population": 20315,
    "nom": "L'Isle-sur-la-Sorgue",
    "_score": 0.0682040929276015
  }
]

On identifie alors mieux la structure de la réponse au format JSON : elle est constituée d’un tableau “anonyme”, délimité par [ et ], constitué d’un seul objet également “anonyme”, délimité par { et }.

Cet objet est composé des attributs code, codesPostaux, centre, population, nom et _score.

Chaque nom d’attribut est exprimé entre guillemets doubles et sa valeur peut prendre la forme :

d’une chaîne de caractères comprise elle-même entre guillemets doubles → Ex. : "nom":"L’Isle-sur-la-Sorgue"
d’un nombre → Ex. : "population":20315
d’un tableau de valeurs délimité par des crochets → Ex. : "coordinates":[5.0588,43.9191]
d'objet délimité par des accolades → Ex. : "centre" : {"type":"Point", "coordinates":…}

On remarquera à la même occasion qu’un attribut de type “objet” permet une décomposition en sous-éléments.

Ainsi, dans notre exemple, l’attribut centre, qui donne les coordonnées du centre la ville, est un objet composé d’un attribut type de type “chaîne de caractères” et d’un attribut coordinates de type “tableau”.

On peut également trouvé dans du JSON les valeurs null, true ou false.

🞄 🞄 🞄