Building a mini API in PHP

Sept leçons à lire le menu. Aujourd'hui, on le cuisine.

Depuis la leçon 2, on interroge la même API : la bibliothèque. GET /livres, POST /livres, un 404 sur un livre qui n'existe pas. À chaque fois, tu envoyais des requêtes à un serveur imaginaire qui répondait comme par magie. Aujourd'hui, on enlève la magie. On l'écrit, ce serveur.

Pas de framework. Pas de Symfony, pas de Laravel. Du PHP natif, avec ce que tu sais déjà : PDO pour la base, json_encode pour le contrat. Le but n'est pas de faire « pro », c'est de voir le squelette nu de toute API : une requête entre, on regarde sa méthode et son URI, on décide quoi faire, on renvoie une réponse. C'est tout. Chaque framework rajoute du confort par-dessus ce squelette. Le comprendre, c'est comprendre tous les autres.

À la fin de cette leçon, l'API que tu interrogeais depuis sept leçons existera, ligne par ligne, sortie de tes mains.

Le plan : un seul point d'entrée

Tout passe par un seul fichier : api/index.php. Une requête arrive, peu importe l'URL exacte, c'est ce fichier qui la reçoit. Il regarde deux choses : la méthode HTTP (GET, POST, PUT, DELETE) et l'URI (/livres ou /livres/88). Avec ce couple, il décide quoi faire.

C'est exactement le squelette de tout micro-framework, en version lisible. Un routeur, ce n'est rien d'autre que ça : un grand aiguillage sur [méthode, ressource]. On va le construire pièce par pièce.

Le code, bloc par bloc

Bloc 1 : lire la requête. On récupère la méthode, et on découpe l'URI pour en extraire la ressource (livres) et l'identifiant éventuel (88). C'est ce que la leçon 3 appelait « le verbe et la ressource ».

<?php
// api/index.php : le point d'entrée unique
$methode = $_SERVER['REQUEST_METHOD'];                  // GET, POST, PUT, DELETE (leçon 3)
$chemin  = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$bouts   = explode('/', trim($chemin, '/'));            // ['api', 'livres', '88']
$ressource = $bouts[1] ?? '';                           // 'livres'
$id        = isset($bouts[2]) ? (int) $bouts[2] : null; // 88, ou null

Bloc 2 : le contrat JSON et les réponses. Le corps d'une requête (le JSON envoyé par le client en POST) se lit dans php://input, puis se décode (leçon 5). Et comme on va répondre partout, on s'écrit un helper repondre() : il pose le status code, le bon Content-Type, et encode le JSON.

// Le corps JSON entrant (leçon 5)
$corps = json_decode(file_get_contents('php://input'), true);

// Helper de réponse : status code + en-tête + JSON (leçon 4 et 5)
function repondre(int $code, array $data): void {
    http_response_code($code);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($data, JSON_UNESCAPED_UNICODE);
}

Bloc 3 : les erreurs structurées. Quand quelque chose cloche, on ne renvoie pas du texte au hasard : on renvoie un application/problem+json (leçon 6, la RFC 9457). Un second helper s'en charge.

// Erreur normalisée problem+json (leçon 6, RFC 9457)
function probleme(int $status, string $title, string $detail): void {
    http_response_code($status);
    header('Content-Type: application/problem+json; charset=utf-8');
    echo json_encode(['type' => 'about:blank', 'title' => $title,
                      'status' => $status, 'detail' => $detail], JSON_UNESCAPED_UNICODE);
}

Bloc 4 : le token sur les écritures. Lire un livre est public, mais en créer ou en supprimer un exige un token (leçon 7). On le lit dans l'en-tête Authorization, et on refuse en 401 s'il manque sur une méthode d'écriture.

// Le Bearer token, exigé sur les écritures (leçon 7)
$entetes = getallheaders();
$token   = $entetes['Authorization'] ?? '';
$ecriture = in_array($methode, ['POST', 'PUT', 'DELETE'], true);
if ($ecriture && $token === '') {
    probleme(401, 'Non authentifié', 'Un Bearer token est requis pour écrire.');
    exit;
}

Bloc 5 : le routage. Le cœur. Un match de PHP 8 (vu au cours PHP) sur le couple [méthode, ressource a un id ?]. Chaque branche fait une chose, renvoie un status code de la leçon 4, et s'appuie sur des requêtes PDO que tu sais déjà écrire (esquissées en une ligne).

// L'aiguillage central (match PHP 8, cours PHP)
match (true) {

    // GET /livres → la collection paginée (leçon 6)
    $methode === 'GET' && $ressource === 'livres' && $id === null => (function () use ($pdo) {
        $limit = min(max((int) ($_GET['limit'] ?? 20), 1), 100);   // borné 1..100 (leçon 6)
        $page  = max((int) ($_GET['page'] ?? 1), 1);
        $total = (int) $pdo->query('SELECT COUNT(*) FROM livres')->fetchColumn();
        $rows  = $pdo->query('SELECT * FROM livres LIMIT ' . $limit . ' OFFSET ' . (($page - 1) * $limit))->fetchAll();
        repondre(200, ['data' => $rows, 'meta' => ['page' => $page, 'limit' => $limit, 'total' => $total]]);
    })(),

    // GET /livres/88 → un livre, ou 404 (leçon 4)
    $methode === 'GET' && $ressource === 'livres' && $id !== null => (function () use ($pdo, $id) {
        $stmt = $pdo->prepare('SELECT * FROM livres WHERE id = ?');
        $stmt->execute([$id]);
        $livre = $stmt->fetch();
        $livre ? repondre(200, $livre) : probleme(404, 'Introuvable', 'Aucun livre nº ' . $id . '.');
    })(),

    // POST /livres → validation puis création (leçon 4 : 422, 201)
    $methode === 'POST' && $ressource === 'livres' => (function () use ($pdo, $corps) {
        if (empty($corps['titre'])) {
            probleme(422, 'Validation', 'Le champ titre est obligatoire.');   // 422, pas 400 (leçon 4)
            return;
        }
        $stmt = $pdo->prepare('INSERT INTO livres (titre, auteur) VALUES (?, ?)');
        $stmt->execute([$corps['titre'], $corps['auteur'] ?? null]);
        $nouvelId = (int) $pdo->lastInsertId();
        header('Location: /api/livres/' . $nouvelId);                          // le 201 pointe la ressource créée
        repondre(201, ['id' => $nouvelId, 'titre' => $corps['titre']]);
    })(),

    // PUT /livres/88 → remplace tout l'objet
    $methode === 'PUT' && $ressource === 'livres' && $id !== null => (function () use ($pdo, $corps, $id) {
        $stmt = $pdo->prepare('UPDATE livres SET titre = ?, auteur = ? WHERE id = ?');
        $stmt->execute([$corps['titre'] ?? '', $corps['auteur'] ?? null, $id]);
        repondre(200, ['id' => $id, 'titre' => $corps['titre'] ?? '']);
    })(),

    // DELETE /livres/88 → 204, pas de corps (leçon 4)
    $methode === 'DELETE' && $ressource === 'livres' && $id !== null => (function () use ($pdo, $id) {
        $pdo->prepare('DELETE FROM livres WHERE id = ?')->execute([$id]);
        http_response_code(204);                                               // 204 = succès sans contenu
    })(),

    // tout le reste → 404 propre
    default => probleme(404, 'Route inconnue', 'Cette ressource n\'existe pas.'),
};

Relis ce match : il est ton API. Chaque ligne renvoie à une leçon du cours. Tu n'apprends rien de neuf ici, tu assembles. C'est ça, construire.

À toi : la séquence CRUD de la victoire

Un terminal simulé, branché sur ton API qui tourne enfin. Tu vas la dérouler en entier : lister, créer (avec ton token), relire ce que tu viens de créer, supprimer, et vérifier que c'est bien parti. Toute la boucle, de tes mains.

Documenter : le menu lisible par les machines

Souviens-toi de la leçon 1 : une API, c'est un menu. Le client lit ce qui est disponible et commande. Mais jusqu'ici, ton menu n'existe que dans ta tête et dans ton code. Comment un autre développeur (ou une machine) sait-il que POST /livres attend un titre ?

La réponse standard s'appelle OpenAPI (anciennement Swagger). C'est un fichier qui décrit ton API dans un format que les humains et les machines lisent. Le menu, écrit noir sur blanc.

openapi: 3.1.0
info: { title: API Bibliotheque, version: 1.0.0 }
paths:
  /livres:
    get: { summary: Liste paginee des livres }
    post: { summary: Cree un livre (titre requis), renvoie 201 + Location }

À partir de ce fichier, l'outil Swagger UI génère une page web interactive : la liste de tes endpoints, leurs paramètres, et même un bouton « Try it out » pour tester en direct. La doc n'est plus un document mort à maintenir à la main : elle est générée depuis le contrat. Le menu se met à jour tout seul.

Situer REST en 2026

Tu as appris REST. Mais ce n'est pas le seul style d'API. Pour ne pas être perdu en entretien ou en réunion d'archi, voici la carte, sans guerre de religion :

• REST : le défaut. Simple, universel, basé sur HTTP que tout le monde connaît. C'est le bon choix pour la grande majorité des API publiques et internes. Quand tu hésites, c'est REST.
• GraphQL : utile quand le front a des besoins de données très variables. Au lieu de subir les réponses figées du serveur, le client demande exactement les champs qu'il veut, en une seule requête. Pratique pour des apps mobiles aux écrans très différents.
• gRPC : le service-à-service interne, haute performance. Binaire, rapide, typé. On le trouve entre microservices d'un même système, là où la vitesse prime sur la lisibilité humaine.

Le menu, tu sais le lire ET l'écrire

On boucle là où on a commencé. Leçon 1 : une API, c'est un contrat, un menu entre deux logiciels. À l'époque, tu étais le client : tu lisais le menu et tu commandais. Huit leçons plus tard, tu es passé de l'autre côté du comptoir. Tu sais maintenant lire un menu d'API (le consommer) et l'écrire (le construire). C'est exactement ce qui sépare celui qui « utilise des API » de celui qui « fait des API ».

Tes 8 réflexes, un par leçon :

1. Leçon 1 : une API est un contrat ; REST l'organise au-dessus de HTTP.
2. Leçon 2 : des noms, pas des verbes. /livres/42, jamais /getLivre.
3. Leçon 3 : le verbe HTTP dit l'action. GET lit, POST crée, PUT remplace, DELETE supprime.
4. Leçon 4 : le bon status code. 201 + Location, 204 sans corps, 422 pour la validation.
5. Leçon 5 : le JSON est le contrat de données. Content-Type des deux côtés.
6. Leçon 6 : paginer, filtrer, et structurer les erreurs en problem+json.
7. Leçon 7 : protéger les écritures par token. 401 si absent, 403 si interdit.
8. Leçon 8 : tout assembler. Une requête entre, le routeur aiguille, le JSON repart.