Utilisation de `@RestController` et des annotations de mapping (`@RequestMapping`, `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`)

Définir des contrôleurs REST avec @RestController

Au coeur de la gestion des requêtes web dans Spring se trouve le concept de contrôleur. Pour construire spécifiquement des API RESTful, Spring Boot nous encourage à utiliser l'annotation @RestController. Comme nous l'avons vu précédemment, il s'agit d'une annotation de commodité qui combine @Controller et @ResponseBody.

• @Controller : Marque la classe comme un composant Spring capable de traiter les requêtes web entrantes. Elle est détectée lors du scan des composants.
• @ResponseBody : Appliquée implicitement à toutes les méthodes du contrôleur, elle indique que la valeur retournée par ces méthodes doit être liée directement au corps de la réponse web. Spring utilisera des convertisseurs de messages HTTP (comme Jackson pour JSON) pour sérialiser l'objet retourné dans le format approprié.

En annotant une classe avec @RestController, vous déclarez clairement son rôle : elle sert à exposer des endpoints REST, et ses méthodes retourneront des données (JSON, XML, texte...) plutôt que des noms de vues à résoudre.

package com.certiquizz.monappliboot.controller;

import org.springframework.web.bind.annotation.RestController;

@RestController // Indique que c'est un contrôleur REST
public class ProductController {
    // ... méthodes de mapping des requêtes ici ...
}

@RequestMapping : l'annotation de mapping universelle

Une fois votre contrôleur défini, il faut indiquer quelles méthodes doivent gérer quelles requêtes HTTP. L'annotation fondamentale pour cela est @RequestMapping. Elle est extrêmement flexible et peut être utilisée au niveau de la classe et/ou au niveau de la méthode.

Les principaux attributs de @RequestMapping sont :

• value ou path : Un tableau de chaînes de caractères définissant les chemins d'URL auxquels le contrôleur ou la méthode répondra (ex: "/products", {"/users", "/profiles"}).
• method : Un tableau de méthodes HTTP (RequestMethod.GET, RequestMethod.POST, etc.) que la méthode gérera pour les chemins spécifiés. Si non spécifié, la méthode répondra à toutes les méthodes HTTP pour ce chemin.
• consumes : Spécifie le type de média (Content-Type) que la méthode peut consommer depuis la requête (ex: "application/json"). La requête sera rejetée si son Content-Type ne correspond pas.
• produces : Spécifie le type de média que la méthode peut produire en réponse (ex: "application/json;charset=UTF-8"). Utilisé pour la négociation de contenu basée sur l'en-tête `Accept` de la requête.

Utilisation au niveau de la classe : Appliquer @RequestMapping sur la classe permet de définir un chemin de base pour toutes les méthodes du contrôleur. Les chemins définis au niveau des méthodes seront relatifs à ce chemin de base.

package com.certiquizz.monappliboot.controller;

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/products") // Chemin de base pour toutes les méthodes
public class ProductController {

    @RequestMapping(method = RequestMethod.GET) // Mappé sur GET /api/v1/products
    public String getAllProducts() {
        return "Liste de tous les produits (V1)";
    }

    @RequestMapping(value = "/{id}", method = RequestMethod.GET) // Mappé sur GET /api/v1/products/{id}
    public String getProductById(@PathVariable String id) {
        return "Détails du produit " + id + " (V1)";
    }
}

Utilisation au niveau de la méthode : Permet de spécifier le chemin et la méthode HTTP pour une opération particulière.

Annotations de mapping spécifiques : @GetMapping, @PostMapping, etc.

Bien que @RequestMapping soit puissant, son utilisation peut devenir verbeuse, surtout pour spécifier la méthode HTTP. Pour simplifier et rendre le code plus lisible, Spring fournit des annotations spécifiques pour chaque méthode HTTP majeure. Elles sont des raccourcis pour @RequestMapping(method = ...).

• @GetMapping : Raccourci pour @RequestMapping(method = RequestMethod.GET). Utilisé pour récupérer des ressources.
• @PostMapping : Raccourci pour @RequestMapping(method = RequestMethod.POST). Utilisé typiquement pour créer de nouvelles ressources.
• @PutMapping : Raccourci pour @RequestMapping(method = RequestMethod.PUT). Utilisé pour remplacer complètement une ressource existante (ou la créer si elle n'existe pas, selon la sémantique PUT).
• @DeleteMapping : Raccourci pour @RequestMapping(method = RequestMethod.DELETE). Utilisé pour supprimer une ressource.
• @PatchMapping : Raccourci pour @RequestMapping(method = RequestMethod.PATCH). Utilisé pour appliquer des mises à jour partielles à une ressource.

L'utilisation de ces annotations spécifiques est considérée comme une bonne pratique car elle rend l'intention de chaque méthode immédiatement claire.

package com.certiquizz.monappliboot.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api/v2/products") // Chemin de base pour la V2
public class ProductControllerV2 {

    // GET /api/v2/products
    @GetMapping
    public String getAllProducts() {
        return "Liste de tous les produits (V2)";
    }

    // GET /api/v2/products/{productId}
    @GetMapping("/{productId}")
    public String getProductById(@PathVariable String productId) {
        return "Détails du produit " + productId + " (V2)";
    }

    // POST /api/v2/products
    @PostMapping
    public ResponseEntity createProduct(/* @RequestBody Product product */) {
        // Logique de création...
        String createdProductId = "prod-xyz"; // Simulé
        return ResponseEntity.created(java.net.URI.create("/api/v2/products/" + createdProductId)).body("Produit créé avec ID: " + createdProductId);
    }

    // PUT /api/v2/products/{productId}
    @PutMapping("/{productId}")
    public String updateProduct(@PathVariable String productId /*, @RequestBody Product product*/) {
        // Logique de mise à jour complète...
        return "Produit " + productId + " entièrement mis à jour (V2)";
    }

    // DELETE /api/v2/products/{productId}
    @DeleteMapping("/{productId}")
    public ResponseEntity deleteProduct(@PathVariable String productId) {
        // Logique de suppression...
        System.out.println("Suppression du produit: " + productId);
        return ResponseEntity.noContent().build(); // Code 204 No Content
    }

    // PATCH /api/v2/products/{productId}
    @PatchMapping("/{productId}")
    public String patchProduct(@PathVariable String productId /*, @RequestBody Map updates */) {
        // Logique de mise à jour partielle...
        return "Produit " + productId + " partiellement mis à jour (V2)";
    }
}

Dans cet exemple, nous utilisons les annotations spécifiques pour chaque opération CRUD (Create, Read, Update, Delete) standard sur la ressource "product". L'utilisation de @RequestMapping au niveau de la classe définit le préfixe `/api/v2/products`, et chaque annotation de méthode spécifique complète le chemin et définit la méthode HTTP associée. Nous introduisons également `@PathVariable` pour extraire des valeurs de l'URI, et `ResponseEntity` pour un contrôle plus fin de la réponse, sujets qui seront détaillés ultérieurement.

En combinant @RestController avec ces annotations de mapping, Spring Boot offre un moyen puissant, flexible et déclaratif de définir la structure de vos API RESTful, en liant clairement les requêtes HTTP entrantes aux méthodes Java qui les traitent.