Comprendre les API REST simplement : du web aux données SQL et JSON

Une API peut être vue comme un intermédiaire organisé entre deux systèmes. Au lieu d’aller lire directement dans une base de données ou dans le code d’une application, un système formule une demande à une interface prévue pour cela, puis reçoit une réponse dans un format convenu.

Dans la vie courante, on peut comparer une API à un guichet bancaire. Vous vous rendez à votre banque parce que vous avez besoin d’obtenir une information sur votre compte : votre solde, une opération récente ou un relevé. La banque dispose déjà de ces informations dans son système. Vous, en tant que client, vous ne pouvez pas aller directement consulter les bases internes de la banque. Vous passez donc par un guichet. Ce guichet reçoit votre demande, vérifie que vous êtes autorisé à obtenir cette information, puis vous restitue une réponse claire et exploitable.

Dans cette analogie, la banque représente le système qui détient les données, le guichet représente le point d’accès, et le guichetier joue le rôle d’intermédiaire entre votre demande et les informations stockées. Dans une API, le principe est similaire : une application n’accède pas directement aux tables, aux fichiers ou aux traitements internes d’un système. Elle envoie une demande à une adresse précise, appelée URL, que l’on peut voir comme l’adresse du bon guichet. Si la banque propose plusieurs guichets selon les besoins, il faut se rendre à celui qui permet d’obtenir la bonne information. De la même manière, chaque URL d’API correspond à un point d’entrée précis. L’API reçoit ensuite la demande, vérifie le cadre d’accès, interroge les bonnes données, puis renvoie une réponse structurée, souvent en JSON.

Il faut toutefois préciser un point important : un point d’accès visible ne signifie pas que tout le monde peut consulter n’importe quelle information. De la même manière, une API publique n’expose pas nécessairement des données publiques. Elle peut être ouverte à des acteurs externes tout en restant protégée par des mécanismes d’authentification, d’autorisation et de contrôle des accès.

Sans contrôle d’accès, un point d’entrée exposé serait évidemment problématique. Dans le cas d’une banque, cela reviendrait à permettre à n’importe qui de demander l’historique d’un compte sans vérification d’identité. En architecture logicielle, c’est exactement pour éviter cela qu’une API sérieuse encadre l’accès aux données avec des règles de sécurité claires.

Les systèmes modernes ne vivent presque jamais seuls. Un site web doit récupérer des produits, un portail client doit afficher des factures, un outil d’audit doit lire des données financières, un CRM doit dialoguer avec un ERP, et une application mobile doit synchroniser des informations avec un serveur distant.

Sans API, chaque système devrait accéder directement aux données internes des autres systèmes, ce qui serait fragile, dangereux et difficile à maintenir. L’API permet de contrôler ce qui est exposé, sous quelle forme, avec quelles règles de sécurité et pour quels usages.

Autrement dit, l’API évite de donner les clés de la maison à tout le monde. Elle ouvre seulement la bonne porte, au bon moment, selon des règles connues. Dans un contexte métier, cela permet par exemple à un ERP, à un portail de reporting ou à une plateforme comme IBM Planning Analytics de récupérer des données utiles sans exposer directement toute la structure technique sous-jacente. L’utilisateur voit une information claire dans son interface, tandis que l’API se charge d’aller chercher la bonne donnée au bon endroit.

Quand on parle d’API web aujourd’hui, on parle très souvent d’API REST. Cela signifie généralement qu’une application expose des ressources via des URLs et qu’on interagit avec elles à l’aide des mécanismes standards du web, notamment HTTP.

Dans un langage simple, une API REST organise les échanges autour de ressources identifiables, par exemple des clients, des commandes, des factures ou des produits. Chaque ressource possède une adresse, et l’on utilise une méthode explicite pour indiquer l’action souhaitée.

Dans la pratique, beaucoup d’équipes disent REST même lorsque leur API n’est pas strictement RESTful au sens académique. Ce n’est pas un problème pour apprendre. Pour commencer, il suffit de retenir qu’une API REST est une API web structurée autour de ressources, d’URLs claires et de méthodes standard.

L’URL est l’adresse à laquelle on envoie une demande. Elle contient souvent plusieurs morceaux : le protocole, le domaine, un chemin et parfois des paramètres.

Reprenons l’image du guichet bancaire : l’URL n’est pas le guichetier, mais l’adresse du bon guichet. Elle indique vers quel service la demande doit être envoyée.

Prenons un exemple simple : https://api.exemple.com/customers/42?include=orders

- Le protocole est https.

- Le domaine est api.exemple.com.

- Le chemin /customers/42 désigne ici une ressource précise, par exemple le client numéro 42.

- Le paramètre include=orders indique que l’on souhaite éventuellement enrichir la réponse avec ses commandes.

Une bonne URL doit être lisible, stable et orientée ressource. On demande une ressource identifiable. On n’écrit pas une phrase floue. L’URL n’est pas là pour raconter une histoire, elle est là pour pointer une information ou une action précise.

Une API REST s’appuie généralement sur les méthodes HTTP pour exprimer l’intention de la requête. C’est un point fondamental. L’URL dit ce que l’on vise. La méthode dit ce que l’on veut faire.

GET sert à lire. POST sert à créer. PUT sert souvent à remplacer une ressource existante. PATCH sert à modifier partiellement une ressource. DELETE sert à supprimer. D’autres méthodes existent, mais celles-ci couvrent l’essentiel pour la plupart des usages métier.

Quand on apprend les API, il faut arrêter de voir ces mots comme du vocabulaire technique gratuit. Ce sont simplement des verbes normalisés pour manipuler des ressources via le web.

Une bonne manière d’enseigner les API à des profils non techniques consiste à lire chaque appel comme une phrase structurée.

Par exemple, GET /invoices/125 signifie : je veux lire la facture numéro 125. POST /customers signifie : je veux créer un nouveau client. PATCH /customers/42 signifie : je veux modifier une partie des informations du client 42.

Cette lecture est simple, saine et pédagogique. Elle aide à montrer qu’une API n’est pas mystérieuse. Elle exprime juste une intention sur une ressource via une convention commune.

Une réponse d’API contient généralement plusieurs éléments : un code de statut, parfois des en-têtes techniques, et très souvent un contenu structuré appelé body.

Le body est souvent en JSON. C’est devenu le format dominant des échanges d’API web, car il est à la fois lisible par des humains et facilement interprétable par des applications.

Une réponse peut renvoyer un seul objet, une liste d’objets, un message d’erreur, des métadonnées de pagination ou encore un indicateur de succès.

Les codes de statut HTTP indiquent rapidement si la demande a réussi ou non. Ils sont très pratiques pour lire le résultat d’un échange sans devoir tout inspecter en détail.

Un code 200 signifie en général que la lecture a réussi. Un 201 signifie qu’une création a été effectuée. Un 400 signale souvent une requête invalide. Un 401 signifie que l’utilisateur n’est pas authentifié. Un 403 signifie qu’il n’a pas le droit. Un 404 indique que la ressource n’a pas été trouvée. Un 500 indique une erreur côté serveur.

Pour un profil métier ou audit, ces codes peuvent être vus comme des signaux de diagnostic. Ils permettent de savoir si le problème vient de la demande, des droits, de l’existence de la ressource ou du système cible.

Dans notre analogie bancaire, il faut éviter une confusion fréquente : un guichet visible de l’extérieur ne signifie pas que tout le monde peut obtenir n’importe quelle information. Il peut être ouvert au public tout en exigeant une vérification d’identité et en limitant précisément ce qui est accessible.

De la même manière, une API publique n’expose pas nécessairement des données publiques. Elle désigne surtout une API accessible à des acteurs externes au système, par exemple des partenaires, des clients ou des développeurs tiers. Cette API peut rester fortement protégée par des mécanismes d’authentification, d’autorisation, de quotas et de contrôle des accès.

À l’inverse, une API privée est généralement réservée aux échanges internes entre applications d’une même organisation. Techniquement, elle peut ressembler à une API publique, mais son exposition, sa gouvernance et ses usages sont différents.

La distinction est importante pour un sujet d’architecture, de sécurité ou d’audit. Une API n’est pas seulement un format d’échange. C’est aussi une surface d’exposition à gouverner avec rigueur.

Consommer une API signifie envoyer une requête puis exploiter la réponse. Cela peut être fait par une application web, une application mobile, un script d’automatisation, un ETL, un outil BI ou un connecteur technique.

Dans une application front-end, on envoie souvent une requête HTTP, puis on transforme la réponse JSON pour l’afficher dans une table, une fiche client, un tableau de bord ou un formulaire.

Le point fondamental à comprendre est le suivant : consommer une API ne veut pas dire seulement appeler une URL. Cela veut dire gérer une conversation complète avec un système distant : succès, erreurs, chargement, données manquantes, droits, formats et éventuels écarts de schéma.

Pour des profils familiers avec SQL, l’API devient souvent beaucoup plus claire dès qu’on établit une comparaison directe avec une requête de lecture sur une table.

En SQL, on interroge directement une structure relationnelle. En API, on demande à une interface de nous exposer une vue contrôlée des données. La logique métier, les règles d’accès, les transformations et le format de restitution peuvent être portés par l’API.

Autrement dit, SQL parle directement au moteur de données. L’API, elle, parle à une couche de service qui peut, ensuite, interroger une ou plusieurs bases, reformater les données et appliquer des règles de sécurité.

Le parallèle SQL est utile, mais il ne faut pas confondre les deux. Une API n’est pas seulement une autre syntaxe pour faire du SQL.

L’API peut masquer la structure réelle de la base, agréger plusieurs sources, restreindre certains champs, reformater les noms, enrichir la réponse, journaliser les accès et imposer des validations métier.

Dans beaucoup d’organisations, c’est précisément ce rôle qui rend les API indispensables : elles créent une couche contractuelle entre les consommateurs et les données internes.

Le JSON s’est imposé parce qu’il est simple à lire, léger à transmettre et très naturel pour représenter des objets, des listes et des structures imbriquées.

Là où SQL restitue souvent une logique tabulaire faite de lignes et de colonnes, le JSON permet de représenter plus directement des objets métier complets, avec éventuellement des sous-objets ou des listes associées.

Par exemple, un client peut être renvoyé avec son adresse, ses préférences et ses commandes récentes dans une seule réponse structurée. Cette capacité à représenter des structures hiérarchiques est particulièrement utile pour les applications web modernes.

JSON n’est pas synonyme de NoSQL. C’est une confusion très fréquente. JSON est d’abord un format d’échange ou de représentation de données.

Une API peut très bien renvoyer du JSON alors que ses données sont stockées dans une base relationnelle SQL. À l’inverse, une base NoSQL orientée document peut stocker des structures proches du JSON, mais cela relève du modèle de persistance, pas seulement du format de réponse.

Il faut donc distinguer trois choses : le mode de stockage des données, le mode d’interrogation des données et le format dans lequel on échange les données.

Imaginons une table customers et une table orders. En SQL, on pourrait faire plusieurs requêtes ou une jointure pour reconstituer la vision d’un client avec ses commandes.

Dans une API, il est fréquent de recevoir une réponse plus directement exploitable par l’application, sous forme d’objet métier enrichi.

Cette différence explique pourquoi les équipes front-end, mobile ou intégration aiment souvent travailler avec des APIs bien conçues : elles exposent la donnée dans une forme déjà proche du besoin d’usage.

Une bonne API doit inspirer la clarté. Les URLs doivent être compréhensibles. Les méthodes doivent être cohérentes. Les réponses doivent être structurées. Les erreurs doivent être lisibles. Les règles de sécurité doivent être explicites.

Une mauvaise API, au contraire, mélange les conventions, expose des noms incohérents, renvoie des erreurs opaques, change trop souvent de schéma ou force les consommateurs à deviner ce qu’il faut envoyer.

Pour une entreprise, la qualité d’une API n’est pas un luxe technique. C’est un facteur direct de maintenabilité, d’intégration, de fiabilité et de compréhension transverse entre équipes.

La bonne méthode consiste à progresser en trois temps. D’abord, comprendre l’idée générale : une API est une porte d’accès contrôlée à une ressource. Ensuite, apprendre les conventions minimales : URL, méthode, requête, réponse, statut. Enfin, relier cela à des cas concrets : lecture de clients, création de factures, comparaison avec SQL, lecture de JSON et gestion des erreurs.

Beaucoup de personnes bloquent parce qu’elles commencent trop tôt par des détails d’authentification, des headers complexes ou des frameworks. Il faut d’abord stabiliser la logique conceptuelle.

Une fois cette base comprise, la suite devient beaucoup plus simple : documentation d’API, outils comme Postman, consommation via front-end, intégration back-end, sécurité et versionnement.

Comprendre une API, ce n’est pas apprendre une magie réservée aux développeurs. C’est comprendre comment des systèmes se parlent de manière contrôlée, lisible et standardisée.

REST, HTTP, CRUD, URL, statuts de réponse et JSON ne sont pas des notions séparées. Elles décrivent toutes la même mécanique d’échange, sous des angles complémentaires.

Pour un profil métier, finance, audit ou data, la comparaison avec SQL est souvent le meilleur point d’entrée. SQL aide à comprendre la logique de lecture et de manipulation des données. L’API ajoute la couche de service, de sécurité, de formatage et d’exposition. Et le JSON, lui, permet d’échanger ces données dans une forme simple, souple et adaptée aux applications modernes.