Deux logiciels qui doivent se parler
Imagine le site de la bibliothèque municipale que tu vas construire dans ce cours. Il a deux moitiés. D'un côté, le front : la page que le visiteur voit, écrite en JavaScript, qui affiche la liste des livres. De l'autre, le back : ton code PHP et sa base de données, qui sait vraiment quels livres existent et lesquels sont empruntés.
Ces deux moitiés ne tournent pas au même endroit. Le front est dans le navigateur du visiteur. Le back est sur ton serveur. Alors comment se parlent-ils ?
Pas en HTML. Le front ne veut pas recevoir une page toute faite : il veut les données brutes, pour les afficher à sa façon. Il demande « donne-moi la liste des livres », et le back répond avec une liste de livres, propre, structurée. Ce canal de discussion, ce langage commun entre les deux, c'est l'API. Et l'API, avant tout, c'est un contrat.
L'API, c'est le menu du restaurant
Tu entres dans un restaurant. Tu ne vas pas en cuisine touiller les casseroles. Tu lis le menu, tu passes commande au serveur, et un plat arrive. Tu ignores tout de la cuisine, et ça n'a aucune importance : le menu te dit ce que tu as le droit de demander, et ce que tu vas recevoir.
Une API, c'est exactement ça. Le front est le client. Le back est la cuisine. L'API est le menu : la liste de ce que tu peux demander (« la liste des livres », « le livre numéro 42 ») et la forme de ce que tu reçois en retour. Le client n'a pas besoin de savoir comment la cuisine prépare le plat. Il a juste besoin du menu.
C'est ça, un contrat : les deux côtés se mettent d'accord sur ce qui se demande et ce qui se reçoit, sans dépendre des détails internes de l'autre. Tu peux refaire toute ta cuisine PHP sans rien changer côté front, tant que le menu reste le même.
Où s'arrête la métaphore : le restaurant explique bien ce qu'est une API. Mais il ne dit rien sur la façon d'organiser ce menu. Or il y a une bonne façon et de mauvaises façons. C'est là qu'intervient REST, et c'est tout le sujet de ce cours. On lâche le restaurant ici.
REST : une façon d'organiser le menu
REST n'est pas une technologie. C'est un style, une convention pour organiser une API au-dessus de HTTP. Le terme vient d'une thèse de Roy Fielding en 2000 ; retiens juste l'idée : une bonne API se construit en suivant les règles du web plutôt qu'en les ignorant.
Deux idées fausses circulent partout, et il faut les casser tout de suite.
Fausse idée numéro 1 : « REST veut dire JSON ». Faux. Fielding ne parle d'aucun format de données. Une API REST pourrait répondre en XML, en CSV, en n'importe quoi. JSON est juste le format le plus courant aujourd'hui, par habitude, pas par règle.
Fausse idée numéro 2 : « toute API qui passe par HTTP est REST ». Faux aussi, et c'est le piège le plus fréquent. La plupart des API qu'on croise sont en réalité du RPC déguisé : on appelle des fonctions distantes (getLivres, deleteLivre) en les habillant en URL. Ça marche, mais ce n'est pas REST.
Il existe un test du nez très simple pour les distinguer. Lis ces deux URL à voix haute :
POST /getLivres: ça pue. On a planqué un verbe (get) dans l'adresse, et on lui colle une méthode HTTP (POST) qui n'a rien à y faire.GET /livres: ça respire. L'adresse nomme une chose (les livres), et la méthode HTTP dit l'action (lire).
D'où le mantra qui va te suivre tout le cours, la règle que Google donne à ses propres équipes : les URI sont des noms, les méthodes HTTP sont les verbes. « Noms = bien, verbes dans l'URL = mauvais. » Une URL nomme une ressource ; ce que tu veux en faire, c'est la méthode qui le dit.
Parmi ces quatre URL, une seule respecte vraiment l'esprit REST. Laquelle, et pourquoi les trois autres sentent mauvais ? /getLivres · /api/livres?action=delete · /livres/42 · /deleteLivre?id=42
Voir la réponse
La bonne, c'est /livres/42. Elle nomme une ressource (le livre 42) et rien d'autre : l'action viendra de la méthode HTTP (GET pour le lire, DELETE pour le supprimer). Les trois autres cachent un verbe dans l'adresse : /getLivres et /deleteLivre mettent l'action dans le nom, et /api/livres?action=delete la planque dans un paramètre. Toutes les trois sont du RPC déguisé. Souviens-toi du test du nez : si tu vois un verbe dans l'URL, ça sent le RPC, pas le REST.
Ce que ce cours vise honnêtement
On va construire une API au niveau de la vraie pratique de l'industrie : des ressources bien nommées, les bons verbes HTTP, les bons status codes. C'est ce que font 95 % des API que tu croiseras et que tu construiras. C'est solide, c'est pro, et c'est largement suffisant pour la bibliothèque.
Pour être honnête jusqu'au bout : le « vrai REST » complet selon Fielding va plus loin, avec une idée appelée hypermédia (ou HATEOAS), où chaque réponse contient les liens vers les actions suivantes. C'est élégant, mais quasiment personne ne l'implémente : la grande majorité des API s'arrêtent avant, et s'en portent très bien. On reste donc volontairement à ce niveau pragmatique, hors HATEOAS.
Tu as déjà posé les fondations
Bonne nouvelle : tu ne pars pas de zéro. Le cours HTTP t'a donné le sol sur lequel on va bâtir. La leçon requête-réponse t'a montré comment une demande part et comment une réponse revient. La leçon stateless et cookies t'a expliqué pourquoi le serveur ne se souvient de rien entre deux appels. Tu connais déjà les status codes, et tu as vu CORS.
Tout ça, c'est la plomberie. Une API REST ne réinvente rien : elle se sert de cette plomberie HTTP, proprement. Dans ce cours, on monte d'un cran : on va décider quoi nommer, quel verbe employer, quel code renvoyer, pour transformer cette plomberie en une API que d'autres développeurs prendront plaisir à utiliser.
Le contrat au milieu
Garde cette image en tête : le front et le back ne se touchent jamais directement. Entre eux, l'API joue le rôle du menu, le contrat que les deux respectent.
Two programs that need to talk
Picture the municipal library website you'll build in this course. It has two halves. On one side, the front: the page the visitor sees, written in JavaScript, showing the list of books. On the other, the back: your PHP code and its database, which truly knows which books exist and which are on loan.
These two halves don't run in the same place. The front lives in the visitor's browser. The back lives on your server. So how do they talk to each other?
Not in HTML. The front doesn't want a ready-made page: it wants the raw data, to display it its own way. It asks "give me the list of books", and the back replies with a clean, structured list of books. That channel of conversation, that common language between the two, is the API. And an API, above all, is a contract.
An API is the restaurant menu
You walk into a restaurant. You don't go into the kitchen to stir the pots. You read the menu, you order from the waiter, and a dish arrives. You know nothing about the kitchen, and it doesn't matter at all: the menu tells you what you're allowed to ask for, and what you'll receive.
An API is exactly that. The front is the customer. The back is the kitchen. The API is the menu: the list of what you can ask for ("the list of books", "book number 42") and the shape of what you get back. The customer doesn't need to know how the kitchen cooks the dish. It just needs the menu.
That's what a contract is: both sides agree on what can be asked and what is returned, without depending on each other's internal details. You can rebuild your whole PHP kitchen without touching the front, as long as the menu stays the same.
Where the metaphor stops: the restaurant explains well what an API is. But it says nothing about how to organise that menu. And there is a good way and bad ways. That's where REST comes in, and it's the whole subject of this course. We drop the restaurant here.
REST: a way to organise the menu
REST is not a technology. It's a style, a convention for organising an API on top of HTTP. The term comes from a 2000 thesis by Roy Fielding; just keep the idea: a good API is built by following the rules of the web rather than ignoring them.
Two false ideas circulate everywhere, and we need to break them right now.
False idea number 1: "REST means JSON". Wrong. Fielding mentions no data format at all. A REST API could answer in XML, CSV, anything. JSON is just the most common format today, by habit, not by rule.
False idea number 2: "any API over HTTP is REST". Also wrong, and it's the most common trap. Most APIs you'll meet are actually RPC in disguise: you call remote functions (getLivres, deleteLivre) dressed up as URLs. It works, but it isn't REST.
There's a very simple smell test to tell them apart. Read these two URLs out loud:
POST /getLivres: it stinks. A verb (get) is hidden inside the address, and it's paired with an HTTP method (POST) that has no business there.GET /livres: it breathes. The address names a thing (the books), and the HTTP method states the action (read).
Hence the mantra that will follow you through the whole course, the rule Google gives its own teams: URIs are nouns, HTTP methods are the verbs. "Nouns are good, verbs in the URL are bad." A URL names a resource; what you want to do with it is what the method says.
Among these four URLs, only one truly respects the spirit of REST. Which one, and why do the other three smell bad? /getLivres · /api/livres?action=delete · /livres/42 · /deleteLivre?id=42
Show the answer
The right one is /livres/42. It names a resource (book 42) and nothing else: the action will come from the HTTP method (GET to read it, DELETE to remove it). The other three hide a verb in the address: /getLivres and /deleteLivre put the action in the name, and /api/livres?action=delete tucks it into a parameter. All three are RPC in disguise. Remember the smell test: if you see a verb in the URL, it smells of RPC, not REST.
What this course honestly aims for
We'll build an API at the level of real industry practice: well-named resources, the right HTTP verbs, the right status codes. That's what 95% of the APIs you'll meet and build actually do. It's solid, it's professional, and it's more than enough for the library.
To be fully honest: "true REST" as Fielding defined it goes further, with an idea called hypermedia (or HATEOAS), where each response contains the links to the next actions. It's elegant, but almost nobody implements it: the vast majority of APIs stop before that, and do just fine. So we deliberately stay at this pragmatic level, no HATEOAS.
You've already laid the foundations
Good news: you're not starting from scratch. The HTTP course gave you the ground we'll build on. The request-response lesson showed you how a request leaves and how a response comes back. The stateless and cookies lesson explained why the server remembers nothing between two calls. You already know status codes, and you've seen CORS.
All of that is the plumbing. A REST API reinvents nothing: it uses that HTTP plumbing, cleanly. In this course we step up a level: we'll decide what to name, which verb to use, which code to return, to turn that plumbing into an API other developers will enjoy using.
The contract in the middle
Keep this picture in mind: the front and the back never touch each other directly. Between them, the API plays the role of the menu, the contract both sides respect.
🎯 Pratique
S'entraîner (clique pour ouvrir) :
💬 Ré-explique sans regarder
Explique à un débutant la différence entre « une API » et « REST », avec la métaphore du restaurant et un exemple d'URL qui sent bon.
GET /livres/42 (un nom + une méthode), pas POST /getLivres (un verbe planqué dans l'URL).🧠 Rappel libre
Sans remonter : quel est le « test du nez » pour repérer une API RPC déguisée, et quel mantra résume la bonne façon de nommer ?
/getLivres, /deleteLivre, ou un ?action=delete), c'est du RPC déguisé. GET /livres respire, POST /getLivres pue. Le mantra : les URI sont des noms, les méthodes HTTP sont les verbes. L'adresse nomme la ressource, la méthode dit l'action.⚖️ Juge le code de l'IA
Tu demandes à l'IA une route pour ajouter un livre à la bibliothèque. Elle propose : « POST /api/createLivre, c'est plus explicite, on voit tout de suite que ça crée un livre. » Tu acceptes, ou tu rejettes ?
createLivre plante un verbe dans l'URL, c'est du RPC déguisé. La bonne route REST est POST /api/livres : l'URL nomme la ressource (les livres), et c'est la méthode POST qui exprime « créer ». On ne répète pas l'action dans le nom. Mantra : les URI sont des noms, les méthodes sont les verbes.The contract is set: an API is a menu, REST is the way to organise it. First golden rule: everything is a resource. Lesson 2: naming your URIs like a pro, and fixing the ones that smell bad.
Lesson 2: Resources and URIs →