# Leçon 1 : Introduction aux APIs et Services Web # 1. Qu'est-ce qu'une API ? L'analogie du restaurant Imaginez que vous êtes dans un restaurant. Vous (le client) voulez manger, mais vous ne savez pas comment fonctionne la cuisine. Vous n'avez pas besoin de connaître les recettes, la température du four ou l'organisation des chefs. Pour obtenir votre plat, vous interagissez avec un intermédiaire : le serveur. Vous consultez un menu (une liste d'opérations possibles avec des descriptions), vous passez une commande précise au serveur (une requête), et le serveur retourne en cuisine (le système), transmet votre demande, puis vous rapporte le plat (la réponse). Une **API (Application Programming Interface)**, ou Interface de Programmation d'Application, joue exactement ce rôle de serveur. C'est un ensemble de règles, de protocoles et d'outils qui permet à différentes applications logicielles de communiquer entre elles. Elle définit les types d'appels ou de requêtes qui peuvent être faits, la manière de les faire, les formats de données à utiliser et les conventions à suivre. L'API masque la complexité interne du système (la "cuisine") et expose uniquement les fonctionnalités nécessaires de manière contrôlée et standardisée. Formellement, une API est un contrat entre un fournisseur de services et un consommateur. Ce contrat stipule : "Si tu me fais une requête structurée de cette manière, je te garantirai une réponse structurée de cette autre manière." # 2. Le passage du monolithe aux microservices Pour comprendre l'importance cruciale des APIs, il faut regarder l'évolution de l'architecture logicielle. Autrefois, la plupart des applications étaient des **monolithes** : un seul bloc de code massif contenant toute la logique métier, l'interface utilisateur et l'accès aux données. L'intégration avec d'autres systèmes était complexe, coûteuse et fragile. L'émergence des APIs a permis la révolution des **microservices**. Une application complexe est désormais décomposée en une collection de petits services indépendants, chacun responsable d'une fonction métier spécifique (gestion des utilisateurs, traitement des paiements, notifications, etc.). Ces microservices communiquent entre eux via des APIs bien définies. Cette approche offre une flexibilité, une scalabilité et une résilience immenses. Une équipe peut mettre à jour le service de paiement sans affecter le service de gestion des utilisateurs, tant que le contrat d'API est respecté. # 3. Services Web : Les APIs du réseau Le terme "API" est générique. L'API d'une bibliothèque logicielle (comme la librairie `math` en Python) permet à votre code d'utiliser ses fonctions, mais cette communication se passe au sein du même processus. Un **Service Web (Web Service)** est un type spécifique d'API qui est accessible sur un réseau, le plus souvent via le protocole HTTP (Hypertext Transfer Protocol), le même protocole que votre navigateur utilise pour charger des pages web. Dans ce cours, nous nous concentrerons presque exclusivement sur les services web, car ils sont le pilier de la communication inter-systèmes dans le monde moderne. # 4. Styles architecturaux et protocoles majeurs Il existe plusieurs manières de concevoir des services web. Les plus courantes sont SOAP, REST, GraphQL et gRPC. ## SOAP (Simple Object Access Protocol) C'est un protocole strict et standardisé, souvent considéré comme l'ancêtre des services web modernes. - **Format de données :** Utilise exclusivement le XML (eXtensible Markup Language) pour la structuration des messages. - **Contrat :** Le contrat d'interface est formellement défini dans un fichier WSDL (Web Services Description Language). - **Transport :** Bien qu'il utilise souvent HTTP, il est agnostique au protocole de transport et peut fonctionner sur SMTP (email) ou autre. - **Cas d'usage :** Privilégié dans les environnements d'entreprise (banques, assurances) qui exigent une sécurité, une fiabilité et une gestion des transactions très robustes. ## REST (REpresentational State Transfer) REST n'est pas un protocole, mais un **style architectural**. Il propose un ensemble de contraintes pour concevoir des applications en réseau. Il est plus simple et plus flexible que SOAP, ce qui explique sa domination aujourd'hui. - **Format de données :** Flexible. Le JSON (JavaScript Object Notation) est le plus courant, mais XML, HTML ou texte brut sont possibles. - **Communication :** Utilise les verbes (méthodes) et les standards du protocole HTTP (GET, POST, PUT, DELETE). - **État :** Apatride (Stateless). Chaque requête du client doit contenir toutes les informations nécessaires pour que le serveur la traite. Le serveur ne stocke aucun contexte client entre les requêtes. - **Concept clé :** Tout est une **ressource* * (un utilisateur, un produit, un article) identifiée par une URI (Uniform Resource Identifier). ## Autres styles notables - **GraphQL :** Un langage de requête pour les APIs. Il permet au client de demander précisément les données dont il a besoin, et rien de plus, résolvant les problèmes de sur-extraction (over-fetching) ou de sous-extraction (under-fetching) souvent rencontrés avec REST. Toutes les requêtes sont généralement adressées à un unique point d'accès (endpoint). - **gRPC (Google Remote Procedure Call) :** Un framework haute performance. Il utilise les Protocol Buffers pour sérialiser les données (un format binaire compact et efficace) et s'appuie sur HTTP/2 pour des communications rapides, notamment pour les microservices. # 5. Plongée dans les concepts fondamentaux de REST Étant le style le plus répandu, nous allons détailler ses composants essentiels. ## Les Ressources et URIs En REST, toute entité est une ressource. Une ressource est identifiée par une URI unique. Par exemple : - `https://api.exemple.com/v1/utilisateurs` : Représente la collection de tous les utilisateurs. - `https://api.exemple.com/v1/utilisateurs/123` : Représente l'utilisateur spécifique avec l'identifiant 123. ## Les Méthodes HTTP (Verbes) Les actions sur les ressources sont effectuées à l'aide des verbes HTTP standards : - **GET :** Lire une ressource ou une collection de ressources. C'est une opération sûre (ne modifie pas les données). - **POST :** Créer une nouvelle ressource. Par exemple, envoyer les données d'un nouvel utilisateur à `/utilisateurs`. - **PUT :** Mettre à jour intégralement une ressource existante. Il faut fournir la représentation complète de la ressource. - **PATCH :** Mettre à jour partiellement une ressource existante. On ne fournit que les champs à modifier. - **DELETE :** Supprimer une ressource. ## Les Codes de Statut HTTP Le serveur utilise des codes de statut pour informer le client du résultat de sa requête. Ils sont regroupés par centaines : - **1xx (Information) :** Requête reçue, processus en cours. - **2xx (Succès) :** L'action a été reçue, comprise et acceptée avec succès. (`200 OK`, `201 Created`, `204 No Content`). - **3xx (Redirection) :** Une action supplémentaire est nécessaire pour compléter la requête. (`301 Moved Permanently`). - **4xx (Erreur Client) :** La requête contient une syntaxe incorrecte ou ne peut être satisfaite. (`400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`). - **5xx (Erreur Serveur) :** Le serveur n'a pas réussi à répondre à une requête apparemment valide. (`500 Internal Server Error`, `503 Service Unavailable`). # 6. Format des données et efficacité Le choix du format de données a un impact significatif sur la performance et la facilité d'utilisation d'une API. Le JSON s'est imposé face au XML pour plusieurs raisons : il est moins verbeux, plus facile à lire pour un humain et nativement interprétable par les navigateurs et les langages comme JavaScript. L'efficacité du transfert de données peut être quantifiée. Le gain en efficacité $E$ de l'utilisation de JSON par rapport à XML pour une même charge utile (payload) peut être exprimé comme suit : $$E = \frac{ \displaystyle S_{ \text{ XML } } - S_{ \text{ JSON } }}{ \displaystyle S_{ \text{ XML } }} \times 100\%$$ Où $S_{\text{XML}}$ et $S_{\text{JSON}}$ sont respectivement les tailles des données en XML et en JSON. De plus, la performance d'une API se mesure souvent par sa latence et son débit. La latence moyenne pondérée $L_{\text{avg}}$ pour un point d'accès (endpoint) qui gère différents types d'opérations peut être modélisée par : $$L_{ \text{ avg } } = \frac{ \displaystyle \sum_{i=1}^{N} (w_i \cdot L_i)}{ \displaystyle \sum_{i=1}^{N} w_i} \text{ où } w_i \text{ est la fréquence (poids) du type de requête } i \text{ et } L_i \text{ est la latence observée pour le type de requête } i$$ Cette formule est cruciale pour l'optimisation des performances, car elle permet d'identifier quelles opérations ont le plus d'impact sur l'expérience utilisateur globale. En conclusion, les APIs et les services web sont les engrenages qui font tourner le web moderne. Comprendre leurs principes fondamentaux est la première étape essentielle avant de pouvoir concevoir, consommer et, surtout, sécuriser les pipelines de données qui en dépendent. # 💡 Exemples Concrets ## Exemple de Requête/Réponse REST avec cURL Voici un exemple d'interaction simple avec une API REST publique (JSONPlaceholder) en utilisant l'outil en ligne de commande `cURL`. Nous demandons les informations de l'utilisateur avec l'ID 1. # Requête pour obtenir l'utilisateur avec l'ID 1 # L'option -i inclut les en-têtes de réponse HTTP $ curl -i https://jsonplaceholder.typicode.com/users/1 # Réponse attendue du serveur (simplifiée) HTTP/2 200 OK content-type: application/json; charset=utf-8 ... { "id": 1, "name": "Leanne Graham", "username": "Bret", "email": "Sincere@april.biz", ... } ## Comparaison de format : JSON vs. XML Cet exemple montre la même information (un objet utilisateur simple) représentée en JSON et en XML. Notez la verbosité du XML par rapport à la concision du JSON. *Représentation en JSON* { "id": 123, "nom": "Dupont", "email": "jean.dupont@email.com", "actif": true } <!-- Représentation en XML --> <?xml version="1.0" encoding="UTF-8"?> <utilisateur> <id>123</id> <nom>Dupont</nom> <email>jean.dupont@email.com</email> <actif>true</actif> </utilisateur> # 🧠 Exercices Pratiques **Exercice 1** : Quelle méthode HTTP serait la plus appropriée pour modifier uniquement l'adresse e-mail d'un utilisateur existant sans affecter ses autres informations (comme son nom ou son adresse) ? > *Solution : La méthode `PATCH` est la plus appropriée. `PUT` impliquerait de renvoyer l'intégralité de l'objet utilisateur avec l'e-mail modifié, tandis que `PATCH` est spécifiquement conçu pour les mises à jour partielles.* **Exercice 2** : Vous effectuez un appel `GET` à l'URI `/api/produits/987`. Le serveur vous renvoie un code de statut `404`. Que signifie cette réponse ? > *Solution : Le code de statut `404 Not Found` signifie que le serveur a bien reçu et compris la requête, mais qu'il n'a trouvé aucune ressource correspondant à l'URI demandée. En d'autres termes, le produit avec l'ID 987 n'existe pas dans le système.* **Exercice 3** : Concevez une structure d'URI RESTful pour une API de blog simple qui doit gérer des articles (posts), des auteurs (authors) et les commentaires (comments) associés à chaque article. > *Solution : Une conception RESTful logique pourrait être : - `/authors` : Obtenir la liste de tous les auteurs. - `/authors/{authorId}` : Obtenir les détails d'un auteur spécifique. - `/posts` : Obtenir la liste de tous les articles. - `/posts/{postId}` : Obtenir les détails d'un article spécifique. - `/posts/{postId}/comments` : Obtenir la liste de tous les commentaires pour un article spécifique. - `/comments/{commentId}` : Obtenir les détails d'un commentaire spécifique.* # 📝 À Retenir - Une API est un contrat qui permet à deux applications logicielles de communiquer sans connaître la complexité interne de l'autre. - Les services web sont des APIs accessibles via des protocoles réseau standards comme HTTP. - REST est un style architectural flexible et dominant, basé sur les ressources, les URIs et les verbes HTTP. - Les concepts clés de REST incluent l'apatridie (statelessness), les ressources identifiées par URI, l'utilisation des verbes HTTP (GET, POST, PUT, DELETE) et des codes de statut standards. - JSON est le format de données de facto pour les APIs REST modernes en raison de sa légèreté et de sa facilité de traitement. - SOAP est un protocole plus ancien et plus strict, basé sur XML, encore utilisé dans des contextes d'entreprise nécessitant une forte standardisation.