Chapitre 1.4 : Structure de l'API REST

Temps d'étude : 45 minutes

---

1. API REST : Architecture d'une station spatiale

Imaginez une station spatiale où chaque module dispose de :

• Un port d'amarrage standard (interface unique)

• Une spécialisation claire (module d'habitation, laboratoire, stockage)

• Un système de coordonnées (emplacement précis)

L'API REST (Representational State Transfer) fonctionne selon les mêmes principes :

• Une interface unique pour toutes les ressources

• Une séparation claire des composants

• Adressage via URI (coordonnées spatiales)

💡 Idée clé :

Chaque ressource (planètes, fusées, astronautes) possède une URL unique et interagit via des méthodes HTTP.

---

2. Les 6 principes de REST par analogie spatiale

Principe REST	Analogie avec l'ISS	Signification pour l'API
Interface uniforme	Nœuds d'amarrage standards	Règles identiques pour toutes les requêtes
Stateless	Chaque commande est autonome	Le serveur ne conserve pas l'état du client
Mise en cache	Réserves de provisions locales	Conservation des réponses fréquentes
Client-serveur	Séparation claire : Centre de contrôle ↔ Station	Développement indépendant des composants
Système de couches	Satellites relais	Proxys, équilibreurs de charge
Code à la demande	Téléchargement de logiciels pour les expériences	(Optionnel) Transfert de scripts

---

3. Ressources et URI : Coordonnées spatiales

Chaque objet dans l'API est une ressource avec une adresse unique :

https://api.spacexdata.com/v4/    ← URL de base
          rockets/            ← Collection de fusées
          rockets/5e9d0d95eda69973a809d1ec ← Fusée spécifique (par ID)

Exemples de ressources spatiales :

• GET /stars → Liste des étoiles
• GET /stars/sirius → Données sur Sirius
• POST /satellites → Lancer un nouveau satellite
• PUT /missions/artemis → Mettre à jour une mission

Schéma d'arborescence URI :

[URL de base]
├── /planets          → Collection de planètes
│   ├── /mars         → Ressource "Mars"
│   └── /venus        → Ressource "Vénus"
└── /launches         → Collection de lancements
    ├── /upcoming     → Sous-collection
    └── /latest       → Ressource

---

4. Opérations CRUD via les méthodes HTTP

Opération	Méthode HTTP	Exemple (Station spatiale)	Réponse du serveur
Create	POST	Envoyer un nouveau module	201 Created
Read	GET	Demander des données sur un module	200 OK
Update	PUT	Reconfigurer un module	200 OK
Delete	DELETE	Désamarrer un ancien module	204 No Content

⚡ Exemple de code (Ajout d'un satellite) :

import requests

# Nous utilisons un service de test qui simule la création d'une ressource
new_post = {
    "title": "Nouveau lancement de télescope",
    "body": "Hubble-2 est prêt à être déployé.",
    "userId": 1
}

# Clé API conditionnelle pour la démonstration des en-têtes
headers = {
    "Authorization": "Bearer YOUR_DEMO_KEY",
    "Content-Type": "application/json; charset=UTF-8"
}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    headers=headers
)

if response.status_code == 201:
    print("✅ Article sur le nouveau satellite créé avec succès !")
    print("Réponse du serveur :")
    print(response.json())
else:
    print(f"❌ Erreur ! Statut : {response.status_code}")

---

5. Versioning de l'API : Évolution de la station

Comme l'ISS est mise à jour (Module "Zarya" → "Nauka"), l'API change de versions :

• Dans l'URL : https://api.spacex.com/v4/rockets
• Dans les en-têtes : Accept: application/vnd.spacex-v5+json

Pourquoi c'est important :

• v1 : Fonctionnalité de base
• v2 : Nouveaux champs ajoutés
• v3 : Structure des réponses modifiée

⚠️ Conseil : Spécifiez toujours la version dans vos requêtes, sinon "l'amarrage" pourrait échouer !

---

6. Hypermedia (HATEOAS) : Navigation dans l'espace

La réponse de l'API contient des liens vers des ressources associées — comme une carte de la station :

{
  "id": "iss",
  "name": "Station Spatiale Internationale",
  "crew": 7,
  "_links": {
    "self": { "href": "/stations/iss" },
    "modules": { "href": "/stations/iss/modules" },
    "schedule": { "href": "/stations/iss/schedule" }
  }
}

---

Quiz pour consolidation

1. REST signifie :

a) Rocket Engine System Transfer b) Representational State Transfer c) Remote Space Technology

2. Le principe "Stateless" signifie :

a) Le serveur conserve l'historique des requêtes b) Chaque requête est autonome c) Les données sont transférées uniquement via SSL

3. URI pour obtenir des données sur la fusée Falcon Heavy :

a) POST /rockets/falcon-heavy b) GET /falcon-heavy c) GET /rockets/falcon-heavy

4. Méthode pour la mise à jour complète d'une ressource :

a) PATCH b) POST c) PUT

5. HATEOAS dans une API est :

a) Un système de liens vers des ressources associées b) Un protocole de chiffrement c) Un langage de requête

Vérifier

---

🚀 Résumé du chapitre :

L'API REST est une "architecture de station spatiale" standardisée pour les services web. Retenez :

• Ressources = Objets (fusées, planètes)
• URI = Coordonnées des objets
• Méthodes HTTP = Commandes de contrôle
• Versions = Modernisations de la station

Fin de la préparation ! Dans le prochain chapitre, nous lancerons une "sonde de test" — nous apprendrons à tester les API via Postman.

📌 Pratique : Étudiez la structure de l'API SpaceX et essayez d'exécuter :

GET https://api.spacexdata.com/v4/launches/latest — faites attention à l'URI et à la structure JSON !