Une démonstration pédagogique et visuelle pour comprendre la différence entre une API REST traditionnelle et une API REST avec HATEOAS à travers un exemple concret de commande de pizza.
- Objectif
- Aperçu
- Structure du projet
- Installation
- Utilisation
- Fonctionnalités
- Guide de démonstration
- Démonstration en images
- Comparaison technique
- Contribution
- Ressources
- Licence
Ce projet illustre concrètement les différences conceptuelles et pratiques entre :
- API REST Classique 🔗 - Endpoints fixes, URLs codées en dur
- API REST HATEOAS 🌐 - Hypermedia As The Engine Of Application State, découverte dynamique
Note : Cette démonstration est parfaite pour comprendre le niveau 3 du Richardson Maturity Model
Comment créer des APIs REST robustes et évolutives ? Cette démo montre pourquoi HATEOAS peut être la solution au couplage fort entre clients et serveurs.
| 🔗 REST Classique | 🌐 REST HATEOAS |
|---|---|
| URLs codées en dur | Découverte dynamique des liens |
| Documentation externe | Auto-documentation |
| Couplage fort | Couplage faible |
| Fragile aux changements | Robuste aux évolutions |
demo/
├── pizza-rest/ # API REST traditionnelle
│ ├── package.json
│ └── index.js
├── pizza-hateoas/ # API REST avec HATEOAS
│ ├── package.json
│ └── index.js
├── client-rest/ # Client pour l'API REST traditionnelle
│ ├── index.html
│ ├── styles.css
│ └── app.js
├── client-hateoas/ # Client pour l'API REST avec HATEOAS
│ ├── index.html
│ ├── styles.css
│ └── app.js
├── start-servers.sh # Script de démarrage automatique
├── DEMO_GUIDE.md # Guide détaillé de démonstration
├── README.md # Ce fichier
├── LICENSE # Licence MIT
├── .gitignore # Fichiers à ignorer par Git
└── index.html # Page d'accueil comparative- Node.js v16 ou supérieur
- npm (inclus avec Node.js)
- Un navigateur web moderne
-
Cloner le repository
git clone https://github.com/Amine830/Demo-hypermedia.git cd Demo-hypermedia -
Installer les dépendances
# Pour l'API REST classique cd pizza-rest npm install cd .. # Pour l'API REST HATEOAS cd pizza-hateoas npm install cd ..
# Démarrer les deux serveurs automatiquement
./start-servers.sh-
Démarrer l'API REST classique (Terminal 1)
cd pizza-rest npm start➡️ Serveur disponible sur http://localhost:3000
-
Démarrer l'API REST HATEOAS (Terminal 2)
cd pizza-hateoas npm start➡️ Serveur disponible sur http://localhost:3001
-
Ouvrir la démonstration
Ouvrez
index.htmldans votre navigateur ou accédez directement aux clients :
Les serveurs sont également déployés en ligne :
- API REST Classique : https://demo-hypermedia-rest.onrender.com
- API REST HATEOAS : https://demo-hypermedia.onrender.com
🎯 Configuration automatique : Le projet détecte automatiquement l'environnement (local/production) et utilise les bonnes URLs d'API grâce au fichier
config.js.
- Endpoints fixes prédéfinis
- URLs codées en dur dans le client
- Réponses contenant uniquement les données demandées
- Point d'entrée unique avec découverte progressive des URLs
- Navigation dynamique via les liens dans les réponses
- Auto-documentation via les hyperliens
- Adaptation du client aux actions disponibles
Pour une démonstration complète et détaillée, consultez le Guide de démonstration qui contient :
- 📋 Scripts de présentation étape par étape
- 🎯 Points clés à expliquer
- 💡 Exemples concrets et comparaisons
- 🧪 Tests de robustesse en temps réel
- ❓ Questions fréquemment posées
- 🎨 Conseils pour une présentation efficace
les autres images sont disponibles dans le dossier assets/screenshots/.
Les deux APIs permettent de :
- Consulter le menu des pizzas disponibles
- Commander une pizza
- Suivre l'état de la commande
- Annuler une commande
| Endpoint | REST Classique | REST HATEOAS |
|---|---|---|
| Menu | [{"id":1,"name":"Margherita","price":8},...] |
{"pizzas":[...],"links":[{"rel":"self","href":"/menu"},{"rel":"order","href":"/order"}]} |
| Commande | {"orderId":"abc123","status":"pending"} |
{"order":{...},"links":[{"rel":"track","href":"/track/abc123"},{"rel":"cancel","href":"/order/abc123/cancel"}]} |
| Suivi | {"orderId":"abc123","status":"baking"} |
{"order":{...},"links":[{"rel":"self","href":"/track/abc123"},{"rel":"cancel","href":"/order/abc123/cancel"}]} |
- 🔗 Couplage : HATEOAS réduit le couplage entre client et serveur
- 🚀 Évolutivité : Les APIs HATEOAS évoluent sans casser les clients
- 🔍 Découvrabilité : Les clients découvrent les fonctionnalités dynamiquement
- 🎮 Contrôle : Le serveur contrôle les actions disponibles selon le contexte
Pour tester la robustesse de HATEOAS :
- Changez les URLs de
/v1/vers/v2/dans le serveur HATEOAS - Mettez à jour seulement le point d'entrée dans le client HATEOAS
- Observez que le client HATEOAS continue de fonctionner ✅
- Le client REST classique sera cassé ❌
Les contributions sont les bienvenues ! Pour contribuer :
- Fork le repository
- Créez une branche pour votre feature (
git checkout -b feature/AmazingFeature) - Committez vos changements (
git commit -m 'Add some AmazingFeature') - Push sur la branche (
git push origin feature/AmazingFeature) - Ouvrez une Pull Request
- Code JavaScript ES6+
- Tests unitaires souhaités
- Respect des principes REST et HATEOAS
- Richardson Maturity Model - Les niveaux de maturité REST
- REST APIs must be hypertext-driven - Roy Fielding
- HAL - Hypertext Application Language
- JSON:API - Spécification pour APIs JSON
Vous avez trouvé un bug ? Ouvrez une issue avec :
- Description du problème
- Étapes pour reproduire
- Comportement attendu vs observé
- Screenshots si pertinents
Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.
- Amine NEDJAR - Création initiale - @Amine830
- Inspiration du Richardson Maturity Model
- Communauté REST et HATEOAS
- Étudiants et enseignants pour les retours
⭐ N'hésitez pas à mettre une étoile si ce projet vous a aidé !
📚 Projet créé à des fins pédagogiques pour illustrer les principes des systèmes hypermédias.