Chapitre 2.5 : Routes d'API

Temps d'étude : 45 minutes

---

1. Qu'est-ce qu'une route ? Explication simple

Imaginez que votre contrôleur (PlanetController) est un grand centre de bureaux, et que chacune de ses méthodes (index, store, show) est un département effectuant son propre travail.

Une route (Route) est une plaque d'adresse à l'entrée du bâtiment. Elle indique :

• "Si quelqu'un est arrivé à l'adresse /planets avec la méthode GET — envoyez-le au département index (afficher tout)."
• "Si quelqu'un est arrivé à l'adresse /planets avec la méthode POST et un colis (données) — envoyez-le au département store (créer un nouveau)."

Sans routes, aucune requête du monde extérieur ne trouvera le département dont elle a besoin dans votre code. Le fichier principal pour de telles "plaques d'adresse" dans une API est routes/api.php.

Dans Laravel 11+, il n'y a pas de "carnet d'adresses API" par défaut. Nous l'avons créé nous-mêmes en exécutant la commande php artisan install:api. Nous avons maintenant le fichier routes/api.php — c'est le centre de contrôle principal pour toutes les routes de notre API.

Différence clé entre api.php et web.php :

• Préfixe /api : Laravel ajoute automatiquement /api à toutes les URL de ce fichier. La route /planets se transforme en /api/planets.
• "Sans état" (Stateless) : Il n'y a pas de sessions ni de cookies ici, comme dans une application web normale. Chaque requête est indépendante et doit contenir toutes les informations d'authentification (généralement un jeton API dans les en-têtes).

---

2. La voie du débutant : Créer une route manuellement

Créons une seule route manuellement pour comprendre le principe. Notre objectif est de faire en sorte que l'URL /api/planets affiche la liste de toutes les planètes.

Ouvrez routes/api.php et écrivez :

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\PlanetController; // Indique où se trouve notre contrôleur

//                    (1)           (2)                     (3)
Route::get(      '/planets',    [PlanetController::class, 'index']     );
//   ^               ^                       ^
// (Méthode HTTP)   (URL)                (Quel contrôleur et quelle méthode appeler)

Analysons cette ligne par parties :

1. Route::get(...) — nous disons : "Cette route ne fonctionne que pour les requêtes GET".
2. '/planets' — c'est l'URL que Laravel écoutera. Compte tenu du préfixe /api, l'adresse complète sera http://space-api.test/api/planets.
3. [PlanetController::class, 'index'] — c'est la "destination". Nous disons : "Quand la requête arrive, trouve la classe PlanetController et appelle la méthode index() en elle".

Maintenant, tout est lié ! Requête -> Route -> Contrôleur -> Méthode.

Et si nous devons obtenir une planète par son ID ? Par exemple, /api/planets/5.

// Route pour obtenir une planète spécifique
Route::get('/planets/{planet}', [PlanetController::class, 'show']);

Ici, {planet} est un "modèle" ou une variable. Laravel comprend que n'importe quoi peut se trouver à cet endroit (ID, slug). Il transmet ensuite cette valeur à la méthode show(Planet $planet). Cette "magie", où Laravel trouve lui-même la planète par ID, est appelée Route Model Binding.

---

3. La voie du maître : apiResource — une seule ligne pour les gouverner toutes

Créer chaque route manuellement (pour index, show, store, update, destroy) est fastidieux. Les développeurs Laravel le comprennent, c'est pourquoi ils ont créé un assistant puissant — apiResource.

Supprimez tout ce que nous avons écrit et remplacez-le par une seule ligne :

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\PlanetController;

Route::apiResource('planets', PlanetController::class);

Que fait cette seule ligne sous le capot ? Elle crée automatiquement un ensemble complet de routes pour les opérations CRUD standard que nous avons déjà implémentées dans le contrôleur.

Méthode	URL	Dirigée vers la méthode	Objectif
GET	/api/planets	index()	Obtenir la liste de toutes les planètes
POST	/api/planets	store()	Créer une nouvelle planète
GET	/api/planets/{planet}	show()	Afficher une planète spécifique
PUT/PATCH	/api/planets/{planet}	update()	Mettre à jour une planète existante
DELETE	/api/planets/{planet}	destroy()	Supprimer une planète

Vous pouvez le vérifier par vous-même. Exécutez la commande dans le terminal :

php artisan route:list --path=api

Vous verrez un tableau avec toutes les routes créées. apiResource est votre meilleur ami pour gagner du temps lors de la création d'API standard.

---

4. Missions spéciales et ordre des routes

Et si nous avons besoin d'une route non standard qui n'est pas incluse dans apiResource ? Par exemple, obtenir une planète aléatoire à l'adresse /api/planets/random.

Ajoutons-la. Mais il y a ici un piège mortel dans lequel tombent 9 débutants sur 10.

Ordre incorrect (NE FONCTIONNE PAS !) :

Route::apiResource('planets', PlanetController::class);
Route::get('/planets/random', [PlanetController::class, 'random']); // <-- NE FONCTIONNERA PAS

Pourquoi ? Laravel lit les routes de haut en bas. Il verra Route::apiResource, qui a créé la route GET /planets/{planet}. Lorsque vous demanderez /planets/random, Laravel pensera que "random" est l'ID de la planète, et tentera de trouver une planète avec l'ID "random" dans la base de données, et vous obtiendrez une erreur.

Ordre correct (FONCTIONNE !) :

<?php
use App\Http\Controllers\PlanetController;
use Illuminate\Support\Facades\Route;

// 1. Déclarons d'abord les routes SPÉCIFIQUES
Route::get('/planets/random', [PlanetController::class, 'random']);

// 2. Et seulement ensuite, déclarons les routes GÉNÉRIQUES avec des variables
Route::apiResource('planets', PlanetController::class);

⚠️ Important !

Pour tester la route api/planets/random, vous devez ajouter un nouveau gestionnaire dans PlanetController :

<?php
public function random(Request $request)
{
   $planet = Planet::inRandomOrder()->first();
   return response()->json($planet);
}

Règle : Déclarez toujours les routes plus spécifiques (telles que /random) avant les routes plus génériques et à motifs (telles que /{planet}).

---

5. Regroupement : Mettre de l'ordre

Lorsque le nombre de routes devient important, il est possible et nécessaire de les regrouper.

A. Versioning de l'API Pour ne pas casser à l'avenir les anciennes applications qui utilisent votre API, il est courant d'ajouter une version à l'URL, par exemple /api/v1/....

<?php
Route::prefix('v1')->group(function () {
    // Toutes les routes à l'intérieur de ce groupe obtiendront le préfixe /v1
    // URL finale : /api/v1/planets
    Route::get('/planets/random', [PlanetController::class, 'random']);
    Route::apiResource('planets', PlanetController::class);
});

B. Protection des routes (Middleware) Imaginons que tout le monde puisse consulter les planètes, mais que seules les utilisateurs autorisés puissent les créer, les mettre à jour et les supprimer.

<?php
// Routes publiques, accessibles à tous
Route::get('/planets', [PlanetController::class, 'index']);
Route::get('/planets/{planet}', [PlanetController::class, 'show']);

// Groupe de routes nécessitant un "pass" (authentification)
Route::middleware('auth:sanctum')->group(function () {
    Route::post('/planets', [PlanetController::class, 'store']);
    Route::put('/planets/{planet}', [PlanetController::class, 'update']);
    Route::delete('/planets/{planet}', [PlanetController::class, 'destroy']);
});

Ici, middleware('auth:sanctum') est comme un garde qui vérifie le "pass" de quiconque tente d'accéder aux routes à l'intérieur du groupe.

---

6. Test via Postman

Maintenant que toutes les routes sont établies, il est temps de les tester.

1. Si vous utilisez Herd : Votre site fonctionne déjà à une adresse de type http://space-api.test.
2. Sinon : Lancez le serveur local avec la commande php artisan serve. L'adresse sera http://localhost:8000.

Ouvrez Postman et envoyez les requêtes :

• GET http://space-api.test/api/planets
• GET http://space-api.test/api/planets/random
• POST http://space-api.test/api/planets (n'oubliez pas d'ajouter le corps de requête JSON dans l'onglet Body -> raw -> JSON).

Exemple de requête POST :

{
    "name": "Kepler-186f",
    "description": "Первая планета земного размера в обитаемой зоне",
    "size_km": 15000,
    "solar_system": "Kepler-186",
    "is_habitable": true
}

---

8. Erreurs courantes de routage

1. 404 Not Found

   • URL incorrecte (/api/planet au lieu de /api/planets)
   • Oublié php artisan serve

2. 405 Method Not Allowed

   • Méthode HTTP incorrecte (par exemple, GET au lieu de POST)

3. Contrôleur Manquant

   • Faute de frappe dans le nom du contrôleur (PlanetControler)

4. Collision de Noms de Route

   • Noms de routes en double

---

Quiz de révision

1. Le fichier pour les routes API dans Laravel :

a) routes/web.php b) routes/api.php c) routes/console.php

2. Le préfixe automatique pour les routes API :

a) /admin b) /api c) /v1

3. La méthode pour créer 5 routes CRUD :

a) Route::api() b) Route::resource() c) Route::apiResource()

4. Route::prefix('v1') est utilisé pour :

a) Authentification b) Versioning de l'API c) Mise en cache

5. Affichage de toutes les routes :

a) php artisan route:list b) php artisan list:routes c) php routes

Vérifier

---

🚀 Résumé du chapitre :

Vous avez construit des "routes hyperspatiales" pour l'API spatiale ! Maintenant :

• 🗺️ Tous les points de terminaison sont accessibles via /api/...
• 🔗 Les routes de ressources sont connectées au contrôleur
• 🛡️ Des routes personnalisées ont été ajoutées pour les opérations spéciales
• ✅ Les routes ont été testées via Postman

L'univers est ouvert aux requêtes ! Ensuite, nous allons ajouter une protection contre les "débris spatiaux" – la validation des données.

📌 Vérification :

1. Exécutez php artisan route:list
2. Assurez-vous de voir 5+ routes pour planets
3. Vérifiez le fonctionnement de GET /api/planets dans le navigateur/Postman

⚠️ Si erreur 404 :

• Vérifiez la présence de Route::apiResource dans routes/api.php
• Assurez-vous que le serveur est lancé (php artisan serve)
• Pour Windows : autorisez le port 8000 dans le pare-feu