Créer une API REST Professionnelle

Controllers, DTOs, validation, gestion des erreurs, pagination, filtres avancés et architecture propre : tout ce qu’il faut pour construire des API REST robustes, scalables et réellement professionnelles.

Introduction

Une API REST professionnelle ne se limite pas à exposer des endpoints. Elle doit être cohérente, prévisible, validée, sécurisée, paginée, versionnée et refléter un modèle métier clair. Ce chapitre fournit une méthodologie appliquée dans les projets modernes.

L’objectif est de produire des API lisibles, maintenables, faciles à tester et prêtes pour un usage intensif en production.

Lexique essentiel

Controller
Point d’entrée HTTP exposant les actions de l’application.

DTO
Objet d’échange : maîtrise stricte des entrées et sorties.

Mapper
Composant pour convertir DTO ↔ entités.

Validation
Contrôle strict des données d’entrée (Bean Validation).

Global Exception Handler
Gestionnaire centralisé pour toutes les erreurs API.

Pagination
Limiter et structurer les retours pour les grandes collections.

Filtre / Intercepteur
Composants qui interceptent les requêtes pour audit, logs, sécurité.

1. Structure minimale d’une API REST professionnelle


com.example.app
│
├── application
│   ├── controllers
│   ├── dto
│   ├── mapper
│   └── handlers
│
├── domain
│   ├── model
│   └── services
│
└── infrastructure
    └── repository

Le contrôleur oriente la requête, mais toute la logique métier est dans les services. Pas de règles métier dans le controller → API propre, testable et stable.

Exemple de Controller professionnel


@RestController
@RequestMapping("/orders")
@RequiredArgsConstructor
class OrderController {

    private final OrderService service;

    @PostMapping
    public OrderResponse create(@Valid @RequestBody CreateOrderRequest request) {
        return service.create(request);
    }

    @GetMapping
    public Page<OrderResponse> list(
        @RequestParam int page,
        @RequestParam int size
    ) {
        return service.list(page, size);
    }
}

DTO d’entrée & validation stricte


public record CreateOrderRequest(
    @NotBlank String productId,
    @Min(1) int quantity,
    @NotBlank String customerId
) {}

Objectif : ne jamais exposer directement une entité JPA. Le DTO garantit une API stable, même si la base évolue.

Mapper explicite


@Component
class OrderMapper {

    Order toModel(CreateOrderRequest dto) {
        return new Order(dto.productId(), dto.quantity(), dto.customerId());
    }

    OrderResponse toResponse(Order order) {
        return new OrderResponse(order.id(), order.total(), order.status());
    }
}

Gestion propre et globale des erreurs


@RestControllerAdvice
class ApiExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    ResponseEntity<?> handleValidation(MethodArgumentNotValidException ex) {
        var errors = ex.getBindingResult()
                       .getFieldErrors()
                       .stream()
                       .map(err -> err.getField() + " : " + err.getDefaultMessage())
                       .toList();

        return ResponseEntity.badRequest().body(errors);
    }

    @ExceptionHandler(EntityNotFoundException.class)
    ResponseEntity<?> handleNotFound(EntityNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

Bonnes pratiques :

Un controller = zéro logique métier.
Validation systématique des entrées.
DTO propres, versionnés, documentés.
Gestion globale des erreurs → API stable.
Pagination obligatoire pour les collections.

2. Filtrage, pagination & performances

Une API professionnelle doit permettre filtrage, tri, pagination, et réponses optimisées.

Pagination Spring Boot


Page<Order> result = repository.findAll(PageRequest.of(page, size));

Filtres avancés via Specification


public static Specification<Order> hasStatus(Status status) {
    return (root, query, cb) -> cb.equal(root.get("status"), status);
}

Combiner plusieurs specifications permet un filtrage évolutif sans explosion du code.

Quiz : API REST Pro

Q1. Où doit se trouver la logique métier ?
- A. Dans le controller
- B. Dans un service métier ✔
- C. Dans le repository
Q2. Quel composant gère toutes les erreurs de manière centralisée ?
- A. Le controller
- B. Le @RestControllerAdvice ✔
- C. Le DTO

Exercice d’application

Implémentez un module complet « Produits » avec :
— DTO d’entrée et de sortie
— Validation stricte
— Mapper
— Controller propre
— Service métier
— Gestion des erreurs
— Pagination

Résumé

Une API REST professionnelle repose sur une architecture claire, validée et stable : controllers légers, services métiers robustes, DTO versionnés, gestion centralisée des erreurs, pagination systématique et respect strict des conventions REST.

Navigation de la Formation

Structure d’un Projet Spring Boot → Spring Data JPA & Hibernate →