Dans ce cours, nous allons régulièrement jongler entre deux parties essentielles du web : les côtés client et serveur. Je vous propose donc de rappeler la définition concrète de ces deux parties :

• Côté client : Il s'agit de la partie "publique", "visible" de notre page web, c'est-à-dire tout ce qui sera directement affiché à l'utilisateur et que celui-ci pourra potentiellement modifier via les outils de développement de son navigateur, pour peu que l'internaute soit un peu expérimenté en développement web. Dans le but d'éviter de laisser traîner d'importantes failles de sécurité - en particulier dans le cadre de l'intégration d'un système de paiement -, on partira toujours du principe que côté client, tout est modifiable. On retrouve parmi les langages côté client par exemple le HTML, CSS, JS (et ses dérivés comme jQuery), etc.
• Côté serveur : Il s'agit, contrairement au côté client, de la partie "cachée" de notre page web : aucun des scripts exécuté côté serveur ne pourra jamais être vu par un internaute, il ne pourra voir que les informations que nous choisirons d'afficher. Il s'agit donc de la partie la plus protégée et sécurisée de notre site (mais elle n'est bien sûr jamais sans faille, il ne faut pas rêver non plus 😅).

Pour faire simple, une API (Application Programming Interface) est une interface de programmation permettant de communiquer et d’échanger des données avec un site tiers. Dans le cas de PayPal, l’utilisation d’une API nous permettra d’envoyer des requêtes aux serveurs de PayPal afin d’effectuer diverses opérations, dont par exemple :

• « Je suis Utilisateur X de PayPal et je souhaite initialiser un paiement d’un certain montant. » PayPal nous dira alors s’il a bien pu initialiser notre paiement ou non, avec diverses informations correspondantes à ce paiement (nous y reviendrons plus tard).
• « Le paiement que j’ai initialisé a-t-il été complété ? (Ou bien mon client a-t-il annulé sa demande de paiement ?) »
• « Je souhaite confirmer la demande de paiement, peux-tu m’envoyer un récapitulatif de la transaction ? » (Oui c’est bien PayPal que je tutoie ici, au cas où vous vous posiez la question 😛)

Bref, vous l’aurez compris, utiliser l’API fournie par PayPal sera donc inévitable dans la mise en place de notre système de paiement.

Cependant, il faut savoir que différents types d’APIs existent. Par exemple, le système que nous allons découvrir ici, Express Checkout, se base sur une API REST.

Sans aller trop loin dans les détails, le modèle d’API « REST » (Representational State Transfer) est le plus adapté aux besoins du web puisqu’il a été créé dans le but de communiquer simplement entre les côtés client et serveur. En effet, celui-ci est totalement basé sur le fonctionnement du HTTP (HyperText Transfer Protocole) et utilise par conséquent les requêtes définies par ce même protocole. Si vous avez donc l’habitude du PHP ou de tout autre langage web côté serveur – ce qui j’imagine est le cas si vous êtes toujours en train de lire ce cours 😅 – vous devriez déjà avoir utilisé les principaux types de requêtes proposées par le fameux protocole HTTP, à savoir « GET » et « POST ».

Il ne s’agit là que d’un gros résumé de ce qu’est une API REST ; je vous invite à faire un tour sur ce cours d’OpenClassrooms qui traite très bien le sujet si vous voulez être 200% à jour et opérationnel sur ce type d’API.

A simple titre indicatif, l’autre système de PayPal (IPN) se base quant à lui sur une API NVP/SOAP. D’autres modèles plus anciens et bien moins adaptés aux besoins actuels du web, en particulier à cause de leur non prédisposition à la communication client-serveur tout en conservant une certaine indépendance entre les deux parties (comme le fait très bien REST). Mais je vais m’arrêter là sur ce type d’API, puisqu’il ne nous intéresse pas plus dans ce cours. Sachez tout de même que NVP et SOAP sont des modèles toujours existants et qu’il peut être tout à fait légitime de les utiliser dans certains cas (et non, je ne dis pas ça pour éviter d’attirer les commentaires des puristes de ces modèles, enfin pas que 😆).

Comme vous le savez déjà, le web se compose des deux côtés client et serveur bien distincts. Il peut être très pratique d'établir une connexion entre ces deux parties sans pour autant demander au client (au navigateur) de recharger l'intégralité de la page, et c'est exactement à cela que vont nous servir les requêtes asynchrones. Ces requêtes ont donc l'avantage - à l'instar des requêtes synchrones - de pouvoir être effectuées même une fois le chargement de la page totalement terminé et de rendre ainsi plus fluide la navigation d'un site internet. C'est effectivement le client (du code JS par exemple) qui se chargera directement de contacter notre serveur (de lui envoyer une requête pour utiliser le terme exact).

Concrètement, Ajax (Asynchronous JavaScript And Xml) et XMLHttpRequest sont les fonctions généralement utilisées pour effectuer ce type de requêtes. Par abus de langage, je vais me permettre de dire qu'Ajax (disponible en jQuery) est en quelque sorte une amélioration de XMLHttpRequest (disponible à la base en JavaScript). Décomposons donc ce mot à l'apparence barbare :

• XML : un langage de balisage, en particulier celui utilisé par HTML (HyperText Markup Language)
• Http : un protocole de communication entre client et serveur (HyperText Transfer Protocole - on retrouve comme par hasard le début du "HTML" dans le nom de ce protocole)
• Request : une requête

Ainsi, vous comprendrez que XMLHttpRequest définie simplement l'envoi de données XML via des requêtes HTTP, autrement dit il s'agit de nos requêtes asynchrones. Cependant, nous n'utiliserons pas dans notre cas des données au format XML, mais au format JSON (JavaScript Object Notation) de façon à simplifier la communication client/serveur.

Voici donc comment fonctionne une requête asynchrone :

• Le client envoie une requête HTTP au serveur (avec éventuellement certains paramètres) qui peut être GET, POST, etc.
• Le serveur traite cette requête (en PHP par exemple, ou avec tout autre langage serveur) et renvoie certaines informations (en réalité, le serveur affiche des informations, on utilise souvent le terme "renvoie" par abus de langage, en PHP elles seront donc simplement affichées à l'aide d'un "echo").
• Ces informations sont récupérées par le client (JS) et peuvent être utilisées de nombreuses manières comme par exemple afficher un message à l'utilisateur.

Prenons un exemple concret d'utilisation des requêtes asynchrones : Vous avez sur votre site internet un formulaire de contact et souhaitez que le formulaire soit posté (en PHP) sans pour autant recharger la page dans son intégralité. Vous pourrez dans ce cas détecter l'envoi du formulaire en JS (côté client), bloquer le comportement normal du formulaire qui aurait généré un rechargement de la page (toujours en JS) et enfin appeler un script côté serveur (en PHP) en lui passant les paramètres de votre formulaire. Ce script PHP (donc côté serveur) vous renverra ensuite certaines données vous indiquant notamment si l'envoi du formulaire a bien réussi ou non. Vous n'aurez alors plus qu'à afficher un message à l'utilisateur pour lui indiquer si le formulaire de contact qu'il a rempli a bien été posté, et tout se sera passé pour lui comme si tout était toujours resté côté client durant l'envoi de son formulaire ! Magique, non ? 😏

Comme je vous l'ai annoncé plus haut, nous nous servirons de données au format JSON pour faciliter la communication entre client et serveur. Mais alors, de quoi s'agit-il ? En réalité, le principe du JSON est assez simple : il s'agit d'un format de données utilisé à la base en particulier en JavaScript (d'où son nom) et permettant de structurer des ensembles de données. Le principe peut donc sembler similaire au XML (qui permet également de structurer des données), à un détail près : le JSON est plus léger et s'adapte bien plus facilement entre les différents langages de programmation.

Il nous suffira par exemple en PHP de créer un tableau tout ce qu'il y a de plus classique (voire des tableaux imbriqués dans d'autres tableaux si nécessaire), et la fonction déjà prévue en PHP json_encode() nous permettra de convertir automatiquement notre tableau de données au format JSON de façon à ce que ces données puissent être exploitées par tout autre langage supportant le JSON, dans notre cas JavaScript côté client.

Voici par exemple à quoi ressemblera un simple tableau PHP une fois encodé en JSON (exemple issu de la documentation PHP officielle de la fonction json_encode()) :

<?php
$arr = array('a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5);

echo json_encode($arr);
// Affiche : {"a":1,"b":2,"c":3,"d":4,"e":5}
?>

En supposant que ce tableau JSON soit stocké dans une variable "data" en JavaScript, on pourra par exemple accéder à la valeur ayant pour clé "d" (c'est-à-dire 4) grâce à la notation suivante :

var data = {"a":1,"b":2,"c":3,"d":4,"e":5};
alert(data.d); // Affiche un message d'alerte JavaScript contenant "4";

Etant donné qu'il s'agit uniquement de code JavaScript côté client, vous pouvez d'ailleurs le copier/coller directement dans la console JS de votre navigateur pour le tester si vous le souhaitez 😉 (Il faut appuyer sur la touche F12 pour ouvrir la console JS sur Firefox et Google Chrome)