Laravel : installer et créer des routes API

par

Cela faisait quelque temps que je voulais faire cet article, mais comme d’habitude, c’est une ressource qu’il me manque donc il n’arrive que maintenant. Il s’agit d’un tutoriel qui j’espère vous sera utile pour maîtriser les bases des routes API dans Laravel. Je ferais sûrement d’autres articles plus complets par la suite sur le sujet et ici, je vais vraiment traiter ce que vous devez absolument savoir sur le fichier api.php de Laravel.

La nouvelle version de Laravel 11 apporte plusieurs modifications notables, notamment une structure de projet allégée. L’une des modifications concerne la gestion des routes API. Contrairement aux versions précédentes, Laravel 11 ne présente plus le fichier de route api.php par défaut, car il n’est pas utilisé dans toutes les applications. Pour ceux qui ont besoin de développer une API, il est maintenant nécessaire de publier ce fichier manuellement. Ce guide vous montrera comment publier et configurer ce fichier et comment créer une simple route pour récupérer des produits.

Pourquoi le fichier de route API est supprimé dans Laravel 11 ?

Dans Laravel 11, le fichier de route API (routes/api.php) a été supprimé par défaut pour alléger la structure initiale de l’application. Cette suppression permet de simplifier le framework pour les développeurs qui ne créent pas d’API. Cependant, si vous avez besoin de créer une API, Laravel facilite toujours la mise en place de ce fichier via une commande spécifique.

Cela montre l’approche modulaire de Laravel, qui vise à offrir un cadre de travail optimisé pour tous les types de projets, qu’ils incluent ou non des API. Cette flexibilité permet aux développeurs de ne charger que ce qui est nécessaire pour leur application.

Pourquoi utiliser api.php plutôt que web.php dans Laravel ?

Dans Laravel, les fichiers de routes web.php et api.php sont tous deux utilisés pour définir les routes de votre application. Cependant, ils sont destinés à des usages différents, car Laravel applique différents comportements et configurations en fonction de leur nature. Voici pourquoi vous devriez utiliser api.php pour vos API et web.php pour les routes web traditionnelles.

Des groupes de middleware différents

Le principal avantage d’utiliser api.php plutôt que web.php pour vos routes API réside dans les middlewares qui leur sont assignés par défaut.

  • Fichier web.php : Les routes définies dans web.php sont attribuées au groupe de middleware web. Ce groupe inclut des fonctionnalités spécifiques au comportement d’une application web, telles que :
    • La gestion des sessions : Laravel conserve les données de session entre les requêtes, ce qui est essentiel pour les applications web traditionnelles où les utilisateurs s’authentifient et interagissent avec des formulaires.
    • Protection CSRF (Cross-Site Request Forgery) : Ce middleware protège les formulaires des attaques CSRF en s’assurant que les requêtes POST ou PUT proviennent bien de votre application. Ce type de protection est crucial pour les sites web interactifs, mais généralement non nécessaire pour une API, qui utilise des jetons ou autres méthodes d’authentification.
  • Fichier api.php : Les routes définies dans api.php sont attribuées au groupe de middleware api. Ce groupe est optimisé pour les interactions API sans état (stateless). Les principales différences sont :
    • Aucune gestion des sessions : Les APIs sont souvent sans état, ce qui signifie que chaque requête est traitée indépendamment, sans conserver d’informations de session entre les requêtes. Cela réduit la charge serveur puisque l’état de l’utilisateur n’est pas maintenu.
    • Pas de protection CSRF : Les requêtes API n’utilisent généralement pas de formulaires web, donc la protection CSRF n’est pas nécessaire. Les API se basent plutôt sur des mécanismes d’authentification comme les tokens (JWT, API tokens) ou OAuth.

Performance optimisée pour les API

Les routes définies dans api.php sont optimisées pour les interactions rapides et sans état typiques des API. En supprimant les fonctionnalités inutiles comme la gestion des sessions ou la protection CSRF, Laravel peut traiter les requêtes API plus rapidement et avec une moindre utilisation des ressources.

Cela est particulièrement bénéfique dans les cas où :

  • Vous attendez un grand nombre de requêtes venant de différentes sources (applications mobiles, services tiers, etc.).
  • Vous souhaitez que chaque requête API soit indépendante et traitée en isolation sans dépendre de sessions ou de cookies persistants.

Préfixe automatique /api

Lorsque vous définissez des routes dans api.php, Laravel applique automatiquement le préfixe /api à toutes les routes. Cela signifie que les routes API seront accessibles via des URL comme /api/products ou /api/users. Ce préfixe permet de distinguer clairement les routes destinées à une API des routes web classiques. Si vous définissez vos routes API dans web.php, vous devrez ajouter manuellement ce préfixe à chaque route, ce qui peut rendre la gestion des routes plus complexe et moins claire. Sur une application Laravel avec beaucoup de routes c’est tout de suite beaucoup plus pratique et surtout plus clair. Il est bien évidemment possible de changer cette valeur si besoin. On y reviendra plus tard.

Publier le fichier de route API dans Laravel

Pour créer et configurer une API dans Laravel, la première étape consiste à publier le fichier routes/api.php. Cela peut être fait avec la commande artisan suivante :

php artisan install:api

Ce fichier sera automatiquement créé dans le dossier routes, prêt à accueillir vos routes API.

Création de la première route API

Il s’agit bien évidemment ici de montrer à quoi cela pourrait ressembler et j’espère que ça ne sera pas fait comme ceci dans votre application. Il faudra bien évidemment créer un contrôleur pour y déplacer la logique de votre API, mais dans ce cas précis, je veux rester le plus simple possible. Histoire de montrer ce concept d’API dans le framework Laravel par étapes progressives.

Une fois le fichier routes/api.php créé, vous pouvez commencer à définir vos routes API. Les routes API dans Laravel sont sans état, c’est-à-dire qu’elles n’utilisent pas de session de manière persistante et sont généralement destinées à être utilisées avec des jetons d’authentification. Voici un exemple d’une route simple pour récupérer une liste de produits :

<?php
  
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
  
Route::get('/products', function () {
    return response()->json([
        ['id' => 1, 'name' => 'Produit 1', 'price' => 10.99],
        ['id' => 2, 'name' => 'Produit 2', 'price' => 20.99],
        ['id' => 3, 'name' => 'Produit 3', 'price' => 30.99],
    ]);
});

Lorsque vous accédez à l’URL suivante via une requête GET :

https://votredomaine.com/api/products

Vous obtiendrez une réponse JSON contenant la liste des produits :

[
    {"id": 1, "name": "Produit 1", "price": 10.99},
    {"id": 2, "name": "Produit 2", "price": 20.99},
    {"id": 3, "name": "Produit 3", "price": 30.99}
]

Modification et configuration du préfixe de api.php

Par défaut, toutes les routes API utilisent le préfixe /api. Cependant, si vous souhaitez changer ce préfixe, vous pouvez le faire dans le fichier bootstrap/app.php en modifiant la section dédiée aux routes :

->withRouting(
    api: __DIR__.'/../routes/api.php',
    apiPrefix: 'api/public', // Préfixe personnalisé
    // ...
)

Le lien pour votre API sera maintenant par défaut :

https://votredomaine.com/api/public/products

Ce n’est pas vraiment ce que je conseille de faire et pour moi, il est plus judicieux de le faire directement dans le fichier api.php et c’est ce que nous allons voir toute de suite après.

Ajouter un préfixe directement dans api.php

Je prends l’exemple du cas où vous avez plusieurs versions de votre API. Dans dans une application qui est très utilisée, il est important d’assurer la rétrocompatibilité pour ne pas tout casser chez les clients en cas de mise à jour importante. Pour gérer plusieurs versions d’API, je vais utiliser différents préfixes d’URL pour chaque version d’API. Cela permet de distinguer facilement les routes de la v1 et de la v2.

Dans Laravel, vous pouvez facilement créer des groupes de routes avec des préfixes spécifiques pour chaque version d’API. Voici comment vous pouvez organiser les routes pour la version 1 et la version 2 dans le fichier routes/api.php. Pour réaliser facilement cela, je vais utiliser la fonction prefix() de Laravel. Voici un exemple de comment vous pourriez mettre ça en place :

<?php
  
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')->group(function () {
    Route::get('/products', function () {
        return response()->json([
            ['id' => 1, 'name' => 'Produit 1', 'price' => 10.99],
            ['id' => 2, 'name' => 'Produit 2', 'price' => 20.99],
        ]);
    });
});

Route::prefix('v2')->group(function () {
    Route::get('/products', function () {
        return response()->json([
            ['id' => 1, 'name' => 'Nouveau Produit 1', 'price' => 11.99, 'category' => 'Catégorie A'],
            ['id' => 2, 'name' => 'Nouveau Produit 2', 'price' => 21.99, 'category' => 'Catégorie B'],
        ]);
    });
});

Pour appeler votre API, cela de passe ensuite de la même manière que tout à l’heure, mais avec la version en plus :

https://votredomaine.com/api/v1/products
https://votredomaine.com/api/v2/products

Cette approche vous permet de gérer facilement plusieurs versions d’API sans impacter les utilisateurs qui utilisent encore les anciennes versions. Lorsque vous souhaitez introduire des fonctionnalités ou des modifications majeures, vous pouvez simplement les ajouter à la version 2 (ou une nouvelle version), tout en maintenant les anciennes versions en place pour éviter de casser la compatibilité.

Il est également important de documenter clairement chaque version de votre API pour que les développeurs sachent quelles fonctionnalités sont disponibles dans chaque version et comment les utiliser. Utilisez des outils comme Swagger ou Postman pour créer une documentation interactive et accessible pour chaque version de votre API.

J’espère que ce tutoriel, pour débuter avec les API dans Laravel vous sera utile et que vous pourrez facilement mettre en place des routes API. Comme je disais, il s’agit bien évidemment d’une base et je ferais d’autres articles pour aller plus loin sur ce sujet comme l’authentification à l’aide d’une clé API. Ce sera très utile pour surveiller qui fait quoi et surtout que n’importe qui ne puisse pas faire n’importe quoi et casser votre application.

Laisser un commentaire