APIs REST — Principes fondamentaux

Section 11.3.2 : APIs REST — Principes fondamentaux

🎯 Objectif pédagogique

Comprendre en profondeur le fonctionnement des APIs REST : méthodes HTTP, codes de statut, headers, et structure des requêtes/réponses. Vous serez capable de lire une documentation d'API et de comprendre chaque aspect d'un échange client-serveur.

L'API est le contrat universel du web

En Semaine 1, Marc a fait son premier appel API. Maintenant il faut comprendre en profondeur comment ça fonctionne. Une API REST (Representational State Transfer) est un contrat entre deux logiciels : "tu m'envoies X, je te retourne Y".

Anatomie d'une requête HTTP

GET /api/v1/applications?status=interview&limit=10 HTTP/1.1
Host: api.jobtracker.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
Content-Type: application/json
Accept: application/json

───── DÉCOMPOSITION ─────
GET                    → Méthode HTTP (action)
/api/v1/applications   → Endpoint (ressource)
?status=interview      → Query parameters (filtres)
Host: ...              → Headers (métadonnées)
Authorization: ...     → Authentification
Content-Type: ...      → Format du corps de la requête

Les méthodes HTTP = CRUD

Codes de statut HTTP

# Les codes à connaître par coeur

# ✅ Succès (2xx)
# 200 OK          → Tout va bien
# 201 Created     → Ressource créée (après POST)
# 204 No Content  → Succès, pas de corps (après DELETE)

# ⚠️ Redirection (3xx)
# 301 Moved       → URL changée définitivement
# 304 Not Modified → Pas de changement (cache valide)

# ❌ Erreur client (4xx)
# 400 Bad Request  → Requête mal formée
# 401 Unauthorized → Pas authentifié
# 403 Forbidden    → Authentifié mais pas autorisé
# 404 Not Found    → Ressource inexistante
# 429 Too Many     → Rate limit dépassé

# 💥 Erreur serveur (5xx)
# 500 Internal     → Bug côté serveur
# 502 Bad Gateway  → Proxy/load balancer fail
# 503 Unavailable  → Serveur surchargé/maintenance

Structure d'une API REST bien conçue

# Convention d'URL : /ressource (pluriel)
GET    /api/v1/applications         → Liste des candidatures
GET    /api/v1/applications/42      → Candidature #42
POST   /api/v1/applications         → Créer une candidature
PUT    /api/v1/applications/42      → Remplacer la candidature #42
PATCH  /api/v1/applications/42      → Modifier partiellement #42
DELETE /api/v1/applications/42      → Supprimer #42

# Relations
GET    /api/v1/users/1/applications → Candidatures de l'user 1
POST   /api/v1/applications/42/notes → Ajouter une note à la candidature 42

# Filtres, tri, pagination
GET    /api/v1/applications?status=interview&sort=-date&page=2&limit=20

Headers importants

🏋️ Exercice pratique (15 minutes)

Sans coder, lisez cette documentation d'API et répondez :

API: Open Meteo (météo gratuite, pas de clé API)
Base URL: https://api.open-meteo.com/v1

Endpoint: /forecast
Method: GET
Parameters:
  - latitude (required): float
  - longitude (required): float
  - current_weather (optional): boolean
  - hourly (optional): string (temperature_2m, rain, etc.)
  - daily (optional): string
  - timezone (optional): string

Example:
GET /v1/forecast?latitude=48.86&longitude=2.35&current_weather=true

1. →Quelle URL complète pour la météo actuelle de Paris ?
2. →Comment ajouter la température horaire ?
3. →Quelle méthode HTTP utiliser ?
4. →Un body est-il nécessaire ?