API REST Laravel : versionnement, Sanctum et ressources Eloquent

Une API est un contrat : une fois qu'une application mobile ou un partenaire l'utilise, vous ne pouvez plus la modifier à la légère. Construire une API REST avec Laravel est rapide ; la construire pour qu'elle reste maintenable demande quelques choix dès le départ. Voici les fondations à poser : versionnement, authentification avec Sanctum, API Resources, validation et limitation de débit.

1. Activer les routes d'API

Dans les versions récentes de Laravel, le fichier routes/api.php n'est pas présent par défaut. Une commande l'installe, avec Sanctum :

php artisan install:api

Elle crée le fichier de routes d'API, publie la configuration de Sanctum et ajoute la migration des jetons. Pensez ensuite à lancer php artisan migrate.

2. Versionner dès le premier jour

Le plus simple est de préfixer les routes par la version dans l'URL :

Route::prefix('v1')->group(function () {
    Route::post('/login', [AuthController::class, 'login']);

    Route::middleware('auth:sanctum')->group(function () {
        Route::apiResource('products', ProductController::class);
    });
});

Lorsqu'un changement casse la compatibilité (champ supprimé, format modifié), vous créez un groupe v2 avec ses propres contrôleurs ou ressources, et vous conservez v1 le temps que les clients migrent. Rangez les contrôleurs par version (App\Http\Controllers\Api\V1) pour éviter les mélanges.

3. Authentifier avec Sanctum

Pour une application mobile ou un client tiers, Sanctum émet des jetons d'accès personnels. À la connexion, vérifiez les identifiants et créez un jeton :

public function login(LoginRequest $request)
{
    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        return response()->json(['message' => 'Identifiants invalides.'], 422);
    }

    return response()->json([
        'token' => $user->createToken('mobile')->plainTextToken,
    ]);
}

Le client envoie ensuite l'en-tête Authorization: Bearer <jeton>. Pour une application web de même domaine (SPA), Sanctum propose plutôt une authentification par cookie de session, plus adaptée. Limitez les droits des jetons avec les abilities, prévoyez leur révocation à la déconnexion et ne les stockez jamais en clair côté serveur : Sanctum n'en conserve que l'empreinte.

4. Valider avec des Form Requests

Ne validez jamais dans le contrôleur. Une FormRequest centralise règles et autorisations :

class StoreProductRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name'  => ['required', 'string', 'max:255'],
            'price' => ['required', 'numeric', 'min:0'],
        ];
    }
}

En cas d'échec, Laravel renvoie automatiquement une réponse JSON 422 avec le détail des erreurs, à condition que le client envoie l'en-tête Accept: application/json.

5. Formater avec les API Resources

N'exposez jamais directement vos modèles Eloquent : vous publieriez des colonnes internes et figeriez votre schéma de base de données dans le contrat. Une JsonResource décrit précisément ce qui sort :

class ProductResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'       => $this->id,
            'name'     => $this->name,
            'price'    => $this->price,
            'category' => new CategoryResource($this->whenLoaded('category')),
        ];
    }
}

L'usage de whenLoaded évite les requêtes N+1 : la relation n'est incluse que si le contrôleur l'a chargée (with('category')). Pour les listes, renvoyez une collection paginée : ProductResource::collection(Product::paginate(20)).

6. Utiliser correctement HTTP

Une API cohérente respecte la sémantique du protocole : 201 à la création, 204 à la suppression, 401 sans authentification, 403 sans droit, 404 pour une ressource absente, 422 pour une validation échouée. Le choix des verbes (GET, POST, PUT, PATCH, DELETE) compte autant : consultez notre article sur les verbes HTTP et leurs cas d'usage, et son pendant côté code, les verbes HTTP en PHP.

7. Limiter le débit

Protégez l'API contre les abus avec le middleware throttle, et définissez des limites adaptées dans un RateLimiter (par utilisateur ou par adresse IP). Les routes sensibles comme la connexion méritent une limite plus stricte que la lecture de produits. Cette précaution fait partie des bonnes pratiques de cybersécurité les plus rentables.

8. Documenter et tester

• Générez une documentation OpenAPI (avec un package dédié) pour que les clients connaissent les routes sans lire le code.
• Écrivez des tests de fonctionnalité : authentification, droits, validation, format de réponse.
• Journalisez les erreurs 5xx et surveillez les temps de réponse.

Une API peut aussi servir d'interface à une IA : notre tutoriel sur la création d'un serveur MCP avec laravel/mcp réutilise ces mêmes principes d'authentification et de validation.

Conclusion

Une bonne API Laravel tient en cinq réflexes : versionner, authentifier, valider, formater avec des Resources et limiter le débit. Les poser dès le départ coûte quelques heures ; les ajouter après coup à des clients en production coûte beaucoup plus cher.