Concevoir et consommer des API

openapi: 3.1.0
info:
  title: API de la boutique
  version: 1.0.0
paths:
  /api/orders:
    post:
      summary: Passer une commande
      security:
        - bearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PlaceOrderRequest' }
      responses:
        '201':
          description: Commande créée
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
        '409': { description: Stock insuffisant }
        '422': { description: Données invalides }
        '429': { description: Trop de requêtes, réessayer après l'en-tête Retry-After }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  schemas:
    PlaceOrderRequest:
      type: object
      required: [lines]
      properties:
        lines:
          type: object
          additionalProperties: { type: integer, minimum: 1, maximum: 10 }
    OrderResponse:
      type: object
      required: [id, status, totalInCents]
      properties:
        id: { type: string }
        status: { type: string, enum: [placed, paid, shipped] }
        totalInCents: { type: integer }

<?php

declare(strict_types=1);

// L'entité : tout ce que l'application sait d'un utilisateur
final class User
{
    /** @param list<string> $roles */
    public function __construct(
        public int $id,
        public string $email,
        public string $passwordHash,
        public array $roles,
        public ?string $internalNote,
    ) {
    }
}

// Le DTO de sortie : seulement ce que le client a le droit de voir
final readonly class UserResponse
{
    public function __construct(public int $id, public string $email)
    {
    }

    public static function fromUser(User $user): self
    {
        return new self($user->id, $user->email);
    }
}

// Le DTO d'entrée : seulement les champs que le client a le droit de modifier
final readonly class UpdateProfileRequest
{
    public function __construct(public string $email)
    {
    }

    /** @param array<string, mixed> $data */
    public static function fromArray(array $data): self
    {
        return new self((string) ($data['email'] ?? ''));
    }
}

function newUser(): User
{
    return new User(42, 'alice@example.com', '$2y$12$empreinte.fictive', ['ROLE_USER'],
        'Client difficile');
}

echo "Sortie, en sérialisant l'entité :\n";
echo json_encode(newUser(), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), "\n";
echo "Sortie, en sérialisant le DTO :\n";
echo json_encode(UserResponse::fromUser(newUser())), "\n\n";

// Le client envoie un champ qu'on n'attendait pas
$json = '{"email": "alice@example.org", "roles": ["ROLE_ADMIN"]}';
$body = json_decode($json, true, flags: JSON_THROW_ON_ERROR);

$user = newUser();
foreach ($body as $field => $value) {        // entrée liée directement à l'entité
    if (property_exists($user, $field)) {
        $user->$field = $value;
    }
}
echo 'Entrée liée à l\'entité, rôles : ' . implode(', ', $user->roles) . "\n";

$user = newUser();
$request = UpdateProfileRequest::fromArray($body);  // entrée passée par un DTO
$user->email = $request->email;
echo 'Entrée passée par un DTO, rôles : ' . implode(', ', $user->roles) . "\n";

<?php

declare(strict_types=1);

namespace App\Api;

use Symfony\Component\Validator\Constraints as Assert;

// Ce que le client a le droit d'envoyer, et les règles de forme
final readonly class PlaceOrderRequest
{
    /** @param array<string, int> $lines */
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\All([new Assert\Range(min: 1, max: 10)])]
        public array $lines,
    ) {
    }
}

// Ce que le client a le droit de voir
final readonly class OrderResponse
{
    public function __construct(
        public string $id,
        public string $status,
        public int $totalInCents,
    ) {
    }
}

namespace App\Controller;

use App\Api\OrderResponse;
use App\Api\PlaceOrderRequest;
use App\Application\PlaceOrder;
use App\Entity\User;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\CurrentUser;

final class OrderController extends AbstractController
{
    #[Route('/api/orders', methods: ['POST'])]
    public function place(
        // JSON invalide : réponse 422, sans même entrer dans la méthode
        #[MapRequestPayload] PlaceOrderRequest $request,
        #[CurrentUser] User $user,
        PlaceOrder $placeOrder,
    ): JsonResponse {
        $order = $placeOrder($user, $request->lines);

        return $this->json(
            new OrderResponse(
                $order->getId(),
                $order->getStatus()->value,
                $order->getTotalInCents(),
            ),
            201,
            ['Location' => '/api/orders/' . $order->getId()],
        );
    }
}

<?php

declare(strict_types=1);

// Un JWT signé avec HMAC-SHA256, écrit à la main pour voir ce qu'il contient.
// En vrai, utilise une bibliothèque éprouvée : celle-ci n'est là que pour comprendre.
const SECRET = 'secret-de-demonstration-ne-pas-utiliser';

function base64UrlEncode(string $data): string
{
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

function base64UrlDecode(string $data): string
{
    return base64_decode(strtr($data, '-_', '+/'), true)
        ?: throw new RuntimeException('encodage invalide');
}

function signature(string $header, string $payload): string
{
    return base64UrlEncode(hash_hmac('sha256', "$header.$payload", SECRET, true));
}

/** @param array<string, mixed> $claims */
function createToken(array $claims): string
{
    $header = base64UrlEncode(json_encode(['alg' => 'HS256', 'typ' => 'JWT']));
    $payload = base64UrlEncode(json_encode($claims));

    return "$header.$payload." . signature($header, $payload);
}

/** @return array<string, mixed> */
function verifyToken(string $token, int $now): array
{
    $parts = explode('.', $token);
    if (count($parts) !== 3) {
        throw new RuntimeException('format invalide');
    }
    [$header, $payload, $signature] = $parts;
    $alg = json_decode(base64UrlDecode($header), true)['alg'] ?? 'aucun';
    if ($alg !== 'HS256') {                      // on ne laisse JAMAIS le jeton choisir
        throw new RuntimeException("algorithme refusé : $alg");
    }
    if (!hash_equals(signature($header, $payload), $signature)) {
        throw new RuntimeException('signature invalide');
    }
    $claims = json_decode(base64UrlDecode($payload), true, flags: JSON_THROW_ON_ERROR);
    if ($claims['exp'] < $now) {
        throw new RuntimeException('jeton expiré');
    }

    return $claims;
}

function attempt(string $label, string $token, int $now): void
{
    try {
        $claims = verifyToken($token, $now);
        $roles = implode(', ', $claims['roles']);
        echo "Accepté  $label : utilisateur {$claims['sub']}, $roles\n";
    } catch (RuntimeException $e) {
        echo "Refusé   $label : {$e->getMessage()}\n";
    }
}

$now = 1_800_000_000;                            // une date fixe, pour une sortie stable
$token = createToken(['sub' => '42', 'roles' => ['ROLE_USER'], 'exp' => $now + 900]);
[$header, $payload] = explode('.', $token);

echo "Le jeton a trois parties : en-tête, contenu, signature.\n";
echo 'Contenu, lisible par tous sans la clé : ' . base64UrlDecode($payload) . "\n\n";

attempt('jeton intact', $token, $now);

$forged = base64UrlEncode(json_encode(
    ['sub' => '42', 'roles' => ['ROLE_ADMIN'], 'exp' => $now + 900],
));
attempt('contenu modifié', "$header.$forged." . explode('.', $token)[2], $now);

$none = base64UrlEncode(json_encode(['alg' => 'none', 'typ' => 'JWT']));
attempt('« alg: none »', "$none.$forged.", $now);

attempt('une heure plus tard', $token, $now + 3600);

# config/packages/security.yaml (extrait)
security:
    firewalls:
        api:
            pattern: ^/api
            stateless: true          # pas de session : chaque requête porte son jeton
            access_token:
                # La classe qui transforme le jeton reçu en utilisateur (ou le refuse)
                token_handler: App\Security\ApiTokenHandler
    access_control:
        - { path: ^/api, roles: IS_AUTHENTICATED_FULLY }

# config/packages/rate_limiter.yaml
framework:
    rate_limiter:
        api:
            # Fenêtre glissante : pas de rafale au début de chaque période
            policy: sliding_window
            limit: 300
            interval: '15 minutes'

<?php

declare(strict_types=1);

namespace App\EventSubscriber;

use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\RateLimiter\RateLimiterFactory;

// Appliqué à toutes les routes /api, sans y penser dans chaque contrôleur
final class RateLimitSubscriber
{
    public function __construct(
        private RateLimiterFactory $apiLimiter,      // le limiteur « api » de la configuration
        private Security $security,
    ) {
    }

    // Priorité 5 : après le pare-feu (priorité 8), qui a identifié l'utilisateur
    #[AsEventListener(event: KernelEvents::REQUEST, priority: 5)]
    public function onRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();
        if (!$event->isMainRequest() || !str_starts_with($request->getPathInfo(), '/api')) {
            return;
        }
        // Un compteur par utilisateur connu, sinon par adresse IP
        $key = $this->security->getUser()?->getUserIdentifier() ?? $request->getClientIp();
        $limit = $this->apiLimiter->create($key)->consume();
        if (!$limit->isAccepted()) {
            // 429, avec l'en-tête Retry-After : dans combien de secondes réessayer
            $seconds = $limit->getRetryAfter()->getTimestamp() - time();
            throw new TooManyRequestsHttpException($seconds);
        }
    }
}

<?php

declare(strict_types=1);

// Une API de commandes qui accepte une clé d'idempotence (en-tête Idempotency-Key)
final class OrderApi
{
    /** @var array<int, array<string, mixed>> */
    private array $orders = [];

    /** @var array<string, array{fingerprint: string, response: string}> */
    private array $replies = [];

    /** @param array<string, mixed> $body */
    public function post(array $body, ?string $idempotencyKey = null): string
    {
        $fingerprint = hash('sha256', json_encode($body));
        if ($idempotencyKey !== null && isset($this->replies[$idempotencyKey])) {
            $reply = $this->replies[$idempotencyKey];
            if ($reply['fingerprint'] !== $fingerprint) {
                return '422 : cette clé a déjà servi pour une autre requête';
            }

            return $reply['response'] . ' (réponse rejouée, rien de recréé)';
        }

        $id = count($this->orders) + 1;
        $this->orders[$id] = $body;
        $response = "201 : commande $id créée";
        if ($idempotencyKey !== null) {
            $this->replies[$idempotencyKey] = [
                'fingerprint' => $fingerprint,
                'response' => $response,
            ];
        }

        return $response;
    }

    public function count(): int
    {
        return count($this->orders);
    }
}

$cart = ['lines' => ['KB-01' => 1]];

echo "Sans clé : la réponse se perd, l'application renvoie la requête\n";
$api = new OrderApi();
$api->post($cart);                               // réponse perdue en route
echo '  ' . $api->post($cart) . "\n";
echo "  commandes en base : {$api->count()}\n\n";

echo "Avec une clé, générée une fois par le client et renvoyée telle quelle\n";
$api = new OrderApi();
$key = '0b8f3c2e-5d1a-4e7b-9c6f-2a4d8e1f7b30';
$api->post($cart, $key);                         // réponse perdue en route
echo '  ' . $api->post($cart, $key) . "\n";
echo "  commandes en base : {$api->count()}\n";
echo '  ' . $api->post(['lines' => ['MS-02' => 3]], $key) . "\n";

# config/packages/framework.yaml (extrait)
framework:
    http_client:
        scoped_clients:
            # Injecté par son nom : HttpClientInterface $carrierClient
            carrier.client:
                base_uri: '%env(CARRIER_API_URL)%'
                headers:
                    Authorization: 'Bearer %env(CARRIER_API_TOKEN)%'
                timeout: 2.5          # secondes sans recevoir le moindre octet
                max_duration: 10      # durée maximale de la requête entière
                retry_failed:
                    max_retries: 3
                    delay: 500        # millisecondes avant la première nouvelle tentative
                    multiplier: 2     # puis 1 000, puis 2 000
                    jitter: 0.25      # plus ou moins 25 % de hasard

<?php

declare(strict_types=1);

namespace App\Infrastructure\Carrier;

use App\Application\Port\Carrier;
use Symfony\Contracts\HttpClient\HttpClientInterface;

// L'adaptateur de sortie (fiche 16) : le reste de l'application ne voit que le port Carrier
final class HttpCarrier implements Carrier
{
    public function __construct(private HttpClientInterface $carrierClient)
    {
    }

    public function createShipment(string $orderId): string
    {
        $response = $this->carrierClient->request('POST', '/shipments', [
            'json' => ['order' => $orderId],
            // La même clé à chaque essai pour cette commande : jamais deux colis
            'headers' => ['Idempotency-Key' => 'ship-' . $orderId],
        ]);

        // toArray() lève une exception sur un code 3xx, 4xx ou 5xx, et si le délai est dépassé
        return $response->toArray()['id'];
    }
}

<?php

declare(strict_types=1);

// 5xx, 429, délai dépassé : réessayer peut marcher
final class TemporaryFailure extends RuntimeException
{
}

// 4xx : réessayer ne changera rien
final class PermanentFailure extends RuntimeException
{
}

/**
 * Réessaie avec une attente qui double à chaque échec, plus un peu de hasard (jitter).
 *
 * @param callable(int): void $sleep reçoit l'attente en millisecondes
 */
function withRetry(callable $call, callable $sleep, int $maxAttempts = 5): mixed
{
    for ($attempt = 1; ; $attempt++) {
        try {
            return $call();
        } catch (TemporaryFailure $e) {
            if ($attempt === $maxAttempts) {
                throw $e;
            }
            $delay = min(30_000, 500 * 2 ** ($attempt - 1));   // 500, 1 000, 2 000, 4 000 ms…
            $delay += mt_rand(0, intdiv($delay, 4));           // jusqu'à 25 % de hasard
            $sleep($delay);
        }
    }
}

/** Un partenaire simulé, qui donne les réponses prévues dans l'ordre */
function partner(array $answers): callable
{
    return function () use (&$answers): string {
        $answer = array_shift($answers) ?? 503;
        echo "  réponse $answer";                // la suite de la ligne vient après

        return match (true) {
            $answer === 200 => 'OK',
            $answer >= 500 => throw new TemporaryFailure("erreur $answer"),
            default => throw new PermanentFailure("erreur $answer"),
        };
    };
}

// En test, on n'attend pas vraiment : on note l'attente demandée
$sleep = function (int $ms): void {
    echo ', on attend ' . number_format($ms, 0, ',', ' ') . " ms\n";
};
mt_srand(7);                                     // hasard reproductible : sortie stable

foreach (['Panne passagère' => [503, 502, 200], 'Requête invalide' => [400],
    'Partenaire en panne' => []] as $label => $answers) {
    echo "$label :\n";
    try {
        echo ' : ' . withRetry(partner($answers), $sleep) . "\n";
    } catch (TemporaryFailure | PermanentFailure $e) {
        $why = $e instanceof PermanentFailure ? 'inutile de réessayer' : 'trop d\'essais';
        echo ", abandon : $why\n";
    }
}

<?php

declare(strict_types=1);

// Le secret partagé avec le partenaire, lu en vrai dans une variable d'environnement
const WEBHOOK_SECRET = 'whsec_demonstration_ne_pas_utiliser';
const TOLERANCE = 300;                           // 5 minutes

// Ce que fait le partenaire : il signe l'horodatage et le corps BRUT de la requête
function sign(string $body, int $timestamp, string $secret = WEBHOOK_SECRET): string
{
    return "t=$timestamp,v1=" . hash_hmac('sha256', "$timestamp.$body", $secret);
}

// Ce que fait ton application, AVANT de décoder le JSON
function verify(string $body, string $header, int $now): void
{
    if (preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $header, $match) !== 1) {
        throw new RuntimeException('en-tête de signature mal formé');
    }
    [, $timestamp, $received] = $match;
    if (abs($now - (int) $timestamp) > TOLERANCE) {
        throw new RuntimeException('trop ancien : ce pourrait être un rejeu');
    }
    $expected = hash_hmac('sha256', "$timestamp.$body", WEBHOOK_SECRET);
    if (!hash_equals($expected, $received)) {
        throw new RuntimeException('signature invalide');
    }
}

/** @var array<string, true> $processed les événements déjà traités */
$processed = [];

/** @param array<string, true> $processed */
function receive(
    string $label,
    string $body,
    string $header,
    int $now,
    array &$processed,
): void {
    try {
        verify($body, $header, $now);
        $event = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
        if (isset($processed[$event['id']])) {
            echo "200 ignoré  $label : {$event['id']} déjà traité\n";

            return;
        }
        $processed[$event['id']] = true;
        echo "200 traité  $label : {$event['type']}, {$event['amount']} centimes\n";
    } catch (RuntimeException $e) {
        echo "400 refusé  $label : {$e->getMessage()}\n";
    }
}

$now = 1_800_000_000;
$body = '{"id": "evt_1", "type": "payment.succeeded", "amount": 4990}';

receive('livraison normale', $body, sign($body, $now), $now, $processed);
receive('même événement renvoyé', $body, sign($body, $now + 60), $now + 60, $processed);
$tampered = str_replace('4990', '1', $body);
receive('montant modifié en route', $tampered, sign($body, $now), $now, $processed);
$forged = sign($body, $now, 'secret-devine');
receive('signé avec un autre secret', $body, $forged, $now, $processed);
receive('requête rejouée 1 h après', $body, sign($body, $now), $now + 3600, $processed);

<?php

declare(strict_types=1);

// Test fonctionnel : l'API vue de l'extérieur
namespace App\Tests\Api;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

final class OrderApiTest extends WebTestCase
{
    private const HEADERS = ['HTTP_AUTHORIZATION' => 'Bearer jeton-de-test'];

    public function testPlacingAnOrderReturns201WithoutInternalFields(): void
    {
        $client = static::createClient();
        $client->jsonRequest('POST', '/api/orders', ['lines' => ['KB-01' => 2]],
            self::HEADERS);

        self::assertResponseStatusCodeSame(201);
        self::assertResponseHasHeader('Location');
        $content = $client->getResponse()->getContent();
        $data = json_decode($content, true, flags: JSON_THROW_ON_ERROR);
        self::assertSame(['id', 'status', 'totalInCents'], array_keys($data));
    }

    public function testAQuantityOfZeroIsRejected(): void
    {
        $client = static::createClient();
        $client->jsonRequest('POST', '/api/orders', ['lines' => ['KB-01' => 0]],
            self::HEADERS);

        self::assertResponseStatusCodeSame(422);
    }

    public function testWithoutTokenTheApiAnswers401(): void
    {
        $client = static::createClient();
        $client->jsonRequest('POST', '/api/orders', ['lines' => ['KB-01' => 1]]);

        self::assertResponseStatusCodeSame(401);
    }
}

// Test unitaire de l'adaptateur : aucune requête ne part sur le réseau
namespace App\Tests\Infrastructure\Carrier;

use App\Infrastructure\Carrier\HttpCarrier;
use PHPUnit\Framework\TestCase;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;

final class HttpCarrierTest extends TestCase
{
    public function testItSendsTheSameIdempotencyKeyForAnOrder(): void
    {
        $response = new MockResponse('{"id": "SHP-1"}', ['http_code' => 201]);
        $carrier = new HttpCarrier(new MockHttpClient($response, 'https://carrier.example'));

        self::assertSame('SHP-1', $carrier->createShipment('CMD-1001'));
        self::assertSame('POST', $response->getRequestMethod());
        $headers = $response->getRequestOptions()['headers'];
        self::assertContains('Idempotency-Key: ship-CMD-1001', $headers);
    }
}