Codes de statut, en-têtes et redirections (@HttpCode, @Header, @Redirect)

Succès et redirections se règlent par décorateurs ; les erreurs se signalent en levant une exception.

Le contrôleur d'exemple

📄 src/groupes.controller.ts

import {
  Body, ConflictException, Controller, Delete, ForbiddenException, Get, Header, HttpCode, HttpException,
  HttpStatus, NotFoundException, Param, ParseIntPipe, Post, Query, Redirect, Res,
} from '@nestjs/common';
import type { Response } from 'express';

interface Groupe { id: number; code: string; capacite: number; verrouille: boolean }

@Controller('groupes')
export class GroupesController {
  private groupes: Groupe[] = [
    { id: 1, code: 'DEV101', capacite: 24, verrouille: false },
    { id: 2, code: 'DEV102', capacite: 20, verrouille: true },
  ];

  @Get()
  @Header('Cache-Control', 'public, max-age=60')                 // en-tête fixe
  findAll(@Res({ passthrough: true }) res: Response) {
    res.setHeader('X-Total-Count', String(this.groupes.length));  // en-tête calculé
    return this.groupes;
  }

  @Post()
  create(@Body() body: { code: string; capacite: number }, @Res({ passthrough: true }) res: Response) {
    if (this.groupes.some((g) => g.code === body.code)) {
      throw new ConflictException(`Le groupe ${body.code} existe déjà`);        // 409
    }
    const g = { id: this.groupes.length + 1, verrouille: false, ...body };
    this.groupes.push(g);
    res.location(`/api/groupes/${g.id}`);                                       // 201 + Location
    return g;
  }

  @Post('recalculer')
  @HttpCode(HttpStatus.OK)                                         // 200 au lieu de 201
  recalculer() {
    return { recalcule: true };
  }

  @Delete(':id')
  @HttpCode(HttpStatus.NO_CONTENT)                                 // 204 : pas de corps
  remove(@Param('id', ParseIntPipe) id: number) {
    const g = this.groupes.find((x) => x.id === id);
    if (!g) throw new NotFoundException(`Groupe ${id} introuvable`);             // 404
    if (g.verrouille) throw new ForbiddenException('Ce groupe est verrouillé');   // 403
    this.groupes = this.groupes.filter((x) => x.id !== id);
  }

  @Get('quota')
  quota() {
    throw new HttpException(                                        // statut et corps libres
      { statusCode: 429, erreur: 'Trop de requêtes', reessayerDans: '30 s' },
      HttpStatus.TOO_MANY_REQUESTS,
    );
  }

  @Get('emploi-du-temps')
  @Redirect('https://apcpedagogie.com', 302)                        // redirection fixe
  emploiDuTemps(@Query('groupe') groupe?: string) {
    if (groupe) return { url: `/edt/${groupe.toLowerCase()}`, statusCode: 307 };  // dynamique
  }
}

Requêtes envoyées et réponses réellement obtenues :

GET /api/groupes → 200 [{"id":1,"code":"DEV101","capacite":24,"verrouille":false},{"id":2,"code":"DEV102","capacite":20,"verrouille":true}]  [cache-control: public, max-age=60]  [x-total-count: 2]
POST /api/groupes → 201 {"id":3,"verrouille":false,"code":"INF101","capacite":18}  [location: /api/groupes/3]
POST /api/groupes → 409 {"message":"Le groupe DEV101 existe déjà","error":"Conflict","statusCode":409}
POST /api/groupes/recalculer → 200 {"recalcule":true}
DELETE /api/groupes/3 → 204
DELETE /api/groupes/2 → 403 {"message":"Ce groupe est verrouillé","error":"Forbidden","statusCode":403}
DELETE /api/groupes/9 → 404 {"message":"Groupe 9 introuvable","error":"Not Found","statusCode":404}
GET /api/groupes/quota → 429 {"statusCode":429,"erreur":"Trop de requêtes","reessayerDans":"30 s"}
GET /api/groupes/emploi-du-temps → 302 Found. Redirecting to https://apcpedagogie.com  [location: https://apcpedagogie.com]
GET /api/groupes/emploi-du-temps?groupe=DEV101 → 307 Temporary Redirect. Redirecting to /edt/dev101  [location: /edt/dev101]

1. Les statuts de succès et @HttpCode

• Par défaut : 200, et 201 pour @Post().
• @HttpCode(HttpStatus.OK) sur recalculer: un POST qui ne crée rien répond 200.
• @HttpCode(HttpStatus.NO_CONTENT) sur remove: 204, et le corps est vide même si la méthode renvoyait quelque chose.
• L'énumération HttpStatus évite les « nombres magiques » : HttpStatus.CREATED, HttpStatus.NO_CONTENT, HttpStatus.TOO_MANY_REQUESTS…

2. Les erreurs : lever une exception

On ne « renvoie » pas une erreur : on lève une exception. NestJS l'intercepte (filtre d'exception intégré, leçon 5.5) et construit la réponse { message, error, statusCode }. L'exception peut être levée dans le contrôleur ou, mieux, dans le service.

Pour un statut sans classe dédiée ou une forme de réponse particulière, new HttpException(corps, statut) accepte un objet libre (voir la route quota: 429 avec un corps personnalisé).

3. Les en-têtes de réponse

• En-tête fixe: @Header('Cache-Control', 'public, max-age=60').
• En-tête calculé: @Res({ passthrough: true }) puis res.setHeader('X-Total-Count', …) (leçon 6.1).
• Location après une création: la bonne pratique REST est de renvoyer, avec le 201, l'adresse de la nouvelle ressource (res.location('/api/groupes/3')).

4. Les redirections

• @Redirect(url, statut): redirection fixe (302 par défaut).
• Redirection dynamique: la méthode renvoie { url, statusCode }, qui remplace les valeurs du décorateur. Si elle ne renvoie rien, la redirection fixe s'applique.
• 301: déplacement définitif (les navigateurs et moteurs de recherche le mémorisent) ; 302 / 307: temporaire (307 conserve la méthode et le corps, utile pour un POST).

Activités

@Post()
create(@Body() dto: CreerFormationDto, @Res({ passthrough: true }) res: Response) {
  const f = this.formationsService.create(dto);
  res.location(`/api/formations/${f.id}`);
  return f;
}

@Get()
findAll(@Res({ passthrough: true }) res: Response) {
  const liste = this.formationsService.findAll();
  res.setHeader('X-Total-Count', String(liste.length));
  return liste;
}

create(dto: CreerFormationDto) {
  const existe = this.formations.some((f) => f.intitule.toLowerCase() === dto.intitule.toLowerCase());
  if (existe) throw new ConflictException(`La formation « ${dto.intitule} » existe déjà`);
  …
}

remove(id: number) {
  const f = this.findOne(id);
  if (f.publiee) throw new ForbiddenException('Dépubliez la formation avant de la supprimer');
  …
}

@Get(':id/programme')
@Redirect('/programmes', 302)
programme(@Param('id', ParseIntPipe) id: number) {
  const f = this.formationsService.findOne(id);
  if (f.publiee) return { url: `/programmes/${f.id}` };
}