cours-api-rest.docx

LES API REST

Cours complet pour débutants

Basé sur le cours OpenClassrooms — Adoptez les API REST pour vos projets web

🎯 À qui s'adresse ce cours ? À toi, débutant·e complet·e, qui n'a jamais travaillé ce sujet mais qui veut comprendre les notions clés sans ambiguïté. Les exemples sont volontairement simples et concrets.

PARTIE 1 — Comprendre ce qu'est une API

1.1 C'est quoi une API ?

API signifie Application Programming Interface (Interface de Programmation d'Application).

🍽️ Imagine que tu es au restaurant. Tu ne vas pas toi-même en cuisine chercher ta nourriture. Tu passes par la serveuse, qui transmet ta commande à la cuisine, puis te ramène ton plat. La serveuse, c'est l'API.

En informatique, voici les 3 rôles :

Toi (le client) = ton navigateur, ton appli mobile, ton code
La serveuse (l'API) = l'interface qui fait le lien
La cuisine (le serveur/base de données) = l'endroit où sont stockées les données

✅ En résumé : une API permet à deux applications de communiquer entre elles, sans que l'une ait besoin de connaître le fonctionnement interne de l'autre.

Exemples concrets :

Tu cherches un vol sur Google Flights → Google utilise des API des compagnies aériennes pour afficher leurs tarifs.
Tu te connectes à un site avec ton compte Google → le site utilise l'API de Google.
L'application météo sur ton téléphone récupère les données via une API météo.

1.2 API privée vs API publique

Type	Qui peut l'utiliser ?	Exemple
API publique	N'importe quel développeur	API Twitter, GitHub, Météo
API privée	Seulement les personnes autorisées dans une app/entreprise	L'API interne de ta base de données

🔐 Une API privée ajoute une couche de sécurité : elle évite que n'importe qui accède ou modifie directement ta base de données.

1.3 Pourquoi utiliser une API ?

Sécurité : Sécurité

La base de données n'est pas exposée directement.

Standardisation : Standardisation

Tout le monde parle le même langage via l'API (front-end, mobile, partenaires externes).

Réutilisabilité : Réutilisabilité

Une seule API peut servir à plusieurs applications en même temps.

PARTIE 2 — REST, c'est quoi ?

2.1 Définition

REST = REpresentational State Transfer (Transfert d'état de représentation)

C'est un ensemble de règles architecturales qui définissent comment une API doit se comporter. Ce n'est pas un langage, ni un outil — c'est une façon de concevoir une API.

📊 En 2017, 83 % des API dans le monde étaient des API REST. C'est le standard dominant.

2.2 Les 6 principes fondamentaux de REST

1. Séparation client / serveur

Le client (qui affiche les données) et le serveur (qui les stocke) sont indépendants. L'un peut changer sans impacter l'autre.

2. Sans état — Stateless 🧠 (le plus important !)

Chaque requête envoyée à l'API est complète et indépendante. Le serveur ne se souvient pas des requêtes précédentes.

⚠️ Si la serveuse est "stateless" et que tu lui demandes "Je voudrais du ketchup avec" — elle ne sait pas avec quoi ! Car elle ne se souvient pas que tu viens de commander des frites. Tu dois toujours tout re-préciser à chaque requête.

3. Mise en cache (Cacheable)

Les réponses peuvent être mises en cache côté client pour éviter des requêtes inutiles et aller plus vite.

4. Interface uniforme

La communication entre client et serveur se fait toujours de la même façon standardisée (via des URL + verbes HTTP).

5. Système en couches (Layered System)

Le client ne sait pas s'il parle directement au serveur ou à un intermédiaire (pare-feu, équilibreur de charge...).

6. Code à la demande (optionnel)

Le serveur peut envoyer du code exécutable au client. C'est rare et optionnel.

PARTIE 3 — Les concepts clés d'une API REST

3.1 Ressource et Collection

Une ressource est un objet représenté par un nom. C'est l'unité de base des données dans une API REST.

🛹 Exemple : pour une boutique de skateboards, les ressources pourraient être : Skateboard, Commande, Client, Inventaire.

Une ressource a des attributs (informations supplémentaires). Exemple — un Skateboard a :

un id
un nom
une marque
un prix

Une collection est un ensemble de ressources du même type :

/skateboards → la collection de tous les skateboards

/skateboards/42 → la ressource "skateboard numéro 42"

📌 Convention importante : les noms de ressources et de collections s'écrivent en anglais, au pluriel.

3.2 URI, URL et Endpoint

Terme	Signification	Exemple
URI	Identifiant d'une ressource (comme une étiquette)	/skateboards/42
URL	URI avec l'adresse complète (nom de domaine inclus)	https://api.monsite.com/skateboards/42
Endpoint	L'URL complète utilisée pour faire une requête à l'API	https://api.monsite.com/users/:id

https://api.monsite.com/skateboards/42

|_________________________||________|

Nom de domaine (base URL) Path vers la ressource

✅ Règle d'or : dans un endpoint, utilise des noms (les ressources), jamais des verbes. L'action est portée par le verbe HTTP.

❌ Mauvais : /getSkateboards ou /createSkateboard

✅ Bon : /skateboards (le verbe HTTP dira ce qu'on veut faire)

3.3 Le format des données : JSON

Les données échangées via une API REST peuvent être formatées en JSON (le plus utilisé) ou en XML (plus ancien).

// JSON — le standard actuel

{

"id": 42,

"nom": "Pro Deck",

"marque": "Element",

"prix": 79.99

}

✅ JSON est plus léger, plus lisible et plus facile à utiliser en JavaScript. C'est le standard actuel des API REST.

PARTIE 4 — Faire des requêtes à une API

4.1 Les verbes HTTP et le CRUD

Pour agir sur les ressources, on utilise des verbes HTTP. Ils correspondent aux 4 opérations de base : le CRUD.

CRUD	Verbe HTTP	Action	Exemple
Create (Créer)	POST	Créer une nouvelle ressource	Ajouter un skateboard
Read (Lire)	GET	Récupérer des données	Voir la liste des skateboards
Update (Modifier)	PUT / PATCH	Modifier une ressource existante	Changer le prix
Delete (Supprimer)	DELETE	Supprimer une ressource	Retirer un skateboard

ℹ️ Différence PUT vs PATCH : PUT remplace toute la ressource. PATCH ne modifie qu'une partie seulement.

4.2 La structure d'une requête HTTP

Une requête envoyée à une API contient :

Le verbe HTTP : GET, POST, PUT, DELETE...
L'endpoint (l'URL) : https://api.github.com/users/monpseudo
Les headers : informations de contexte (format souhaité, token d'authentification...)
Le body (optionnel) : les données envoyées avec la requête (pour POST et PUT notamment)

4.3 Les codes de réponse HTTP

Le serveur répond toujours avec un code de statut qui indique si la requête a réussi ou non :

Code	Signification	Quand ?
200 OK	Succès	Requête GET réussie
201 Created	Ressource créée	Requête POST réussie
204 No Content	Succès, pas de contenu à renvoyer	DELETE ou PUT réussi
400 Bad Request	Requête mal formée	Paramètre manquant ou mal formaté
401 Unauthorized	Non authentifié	Token manquant ou invalide
403 Forbidden	Non autorisé	Tu n'as pas les droits
404 Not Found	Ressource introuvable	L'ID n'existe pas
500 Internal Server Error	Erreur côté serveur	Problème de code côté serveur

🧠 Mémo : codes 2xx = succès \| codes 4xx = erreur du client \| codes 5xx = erreur du serveur

PARTIE 5 — Utiliser une API externe en pratique

5.1 Lire la documentation

Avant d'utiliser une API, tu dois lire sa documentation. C'est le manuel d'utilisation. Elle indique :

Les endpoints disponibles
Les verbes HTTP à utiliser
Les paramètres obligatoires ou optionnels
Des exemples de requêtes et de réponses
Les codes d'erreur possibles

📖 Sans documentation, une API est inutilisable. Toujours commencer par là !

5.2 Les paramètres d'une requête

Query parameters (dans l'URL) — pour filtrer, trier, paginer

GET /skateboards?marque=Element&prix_max=100

Path parameters (dans le chemin) — pour cibler une ressource précise

GET /skateboards/42

5.3 L'authentification avec un token

Certaines API nécessitent une authentification. La méthode la plus courante est le token (jeton).

Comment ça fonctionne :

Tu te connectes avec tes identifiants → l'API te donne un token (une longue chaîne de caractères)
Tu envoies ce token dans le header de chaque requête suivante
L'API vérifie le token → si valide, elle répond ; sinon, elle renvoie 401 Unauthorized

// Exemple de header d'authentification :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

🔑 JWT (JSON Web Token) = le format de token le plus répandu. Il contient des informations encodées sur l'utilisateur. C'est cohérent avec le principe stateless : chaque requête se suffit à elle-même grâce au token.

5.4 Tester une API avec Postman

Postman est un outil gratuit qui permet de faire des requêtes à une API sans écrire de code. Idéal pour tester et déboguer.

Avec Postman, tu peux :

Choisir le verbe HTTP (GET, POST...)
Saisir l'endpoint
Ajouter des headers (token d'authentification...)
Rédiger un body (pour POST/PUT)
Voir la réponse et le code de statut

PARTIE 6 — Créer sa propre API REST

6.1 Quand créer sa propre API ?

Il existe deux grandes raisons :

Pour ton application : tu veux une couche API entre ta base de données et ton interface utilisateur (sécurité + organisation).
Pour des tiers : tu veux que d'autres développeurs puissent utiliser tes données.

6.2 Bien concevoir ses endpoints (avant de coder !)

✏️ Avant d'écrire une seule ligne de code, réfléchis à l'architecture de ton API sur papier. Une bonne conception dès le départ évite de nombreuses erreurs.

Les 4 questions à se poser :

Quelles sont mes ressources ? (ex: users, photos, comments)
Quelles opérations CRUD sont nécessaires pour chacune ?
Y a-t-il des ressources imbriquées ? (ex: un commentaire appartient à une photo)
Quels endpoints nécessitent une authentification ?

Exemple concret — app de partage de photos (InstaPhoto) :

GET /photos → Voir toutes les photos (public)

POST /photos → Créer une photo (auth requise)

GET /photos/:id → Voir une photo (public)

DELETE /photos/:id → Supprimer une photo (auth requise)

GET /photos/:id/comments → Voir les commentaires (public)

POST /photos/:id/comments → Ajouter un commentaire (auth requise)

GET /users/:id → Voir un profil (public)

PUT /users/:id → Modifier son profil (auth requise)

6.3 La gestion des erreurs

Une bonne API doit toujours expliquer ses erreurs clairement. Quand quelque chose échoue, renvoie :

Le bon code HTTP (404, 401...)
Un message explicite dans le body

{

"message": "Requires authentication",

"documentation_url": "https://monapi.com/docs/auth"

}

6.4 Bonnes pratiques supplémentaires

Le filtrage, tri et pagination

Quand une collection peut contenir des milliers de ressources, on ne les renvoie pas toutes d'un coup :

GET /skateboards?sort=prix&order=asc&page=2&limit=20

Le versionnage

Pour ne pas casser les applications qui utilisent ton API quand tu la fais évoluer :

https://api.monsite.com/v1/skateboards

https://api.monsite.com/v2/skateboards

La documentation

Une API sans documentation est inutilisable. Elle doit décrire chaque endpoint, ses paramètres, ses exemples de réponse et ses erreurs possibles.

6.5 Les frameworks pour construire une API REST

Framework	Langage	Caractéristiques
Express	JavaScript (Node.js)	Léger, flexible, très populaire
Django REST	Python	Fonctionnalités intégrées, utilisé par Google/Instagram
Ruby on Rails	Ruby	"Magique", grande communauté
Spring Boot	Java	Robuste, utilisé en entreprise
AWS API Gateway	(Interface)	Moins de code, payant par requête

📋 RÉCAPITULATIF — Les notions essentielles

Notion	Définition rapide
API	Interface qui fait le lien entre deux applications
REST	Ensemble de règles pour concevoir une API web
Stateless	Chaque requête est indépendante, le serveur n'a pas de mémoire
Ressource	Un objet de données nommé (ex: un utilisateur, une photo)
Collection	Un ensemble de ressources du même type
URI / Endpoint	L'adresse pour accéder à une ressource
Verbe HTTP	L'action à effectuer (GET, POST, PUT, DELETE)
CRUD	Create, Read, Update, Delete — les 4 opérations de base
JSON	Format de données léger et lisible, standard des API REST
Code HTTP	Numéro indiquant le résultat de la requête (200, 404, 401...)
Token / JWT	Jeton d'authentification envoyé dans chaque requête
Postman	Outil pour tester des API sans coder
Documentation	Manuel d'utilisation indispensable de toute API