API REST : comprendre leur fonctionnement et apprendre à en créer

Les API REST occupent une place essentielle dans le développement des applications modernes. Elles permettent à différents systèmes informatiques de communiquer et d'échanger des données, indépendamment des langages de programmation ou des technologies utilisés.

Qu'il s'agisse d'une application mobile qui récupère des informations depuis un serveur, d'un site web qui consulte une base de données ou d'une plateforme qui communique avec un service de paiement, les API jouent un rôle central dans ces échanges.

Dans cet article, découvrez ce qu'est une API REST, comment elle fonctionne, quels sont les principaux mécanismes qui la composent et comment créer votre propre API avec PHP et MySQL, à travers un exemple pratique.

Introduction

Aujourd'hui, les applications informatiques fonctionnent rarement de manière totalement indépendante.

Une application mobile peut avoir besoin de récupérer les informations d'un utilisateur stockées sur un serveur distant. Un site web peut devoir afficher des produits provenant d'une base de données externe. Une plateforme de réservation peut également communiquer avec un service de paiement pour confirmer une transaction.

Dans toutes ces situations, différents systèmes doivent pouvoir échanger des informations de manière structurée et sécurisée.

C'est précisément le rôle des API (Application Programming Interface), également appelées interfaces de programmation applicative.

Parmi les différentes approches existantes, l'architecture REST (Representational State Transfer) est devenue l'une des plus utilisées pour concevoir des services web.

Sa popularité repose notamment sur l'utilisation des mécanismes standards du protocole HTTP, sa simplicité d'intégration et sa compatibilité avec de nombreux environnements de développement.

Mais comment fonctionne réellement une API REST ? Comment une application mobile communique-t-elle avec un serveur ? Et surtout, comment peut-on concevoir son propre service sans dépendre d'un framework particulier ?

C'est ce que nous allons découvrir.

1. Qu'est-ce qu'une API REST ?

Une API REST est une interface qui permet à plusieurs applications de communiquer à travers le réseau en suivant les principes architecturaux REST.

Pour comprendre cette définition, il faut distinguer deux notions.

API (Application Programming Interface) désigne un ensemble de règles et de mécanismes permettant à un logiciel d'interagir avec un autre logiciel.

REST (Representational State Transfer) désigne un style architectural qui définit des principes pour concevoir des systèmes distribués, notamment des services web.

Une API REST permet donc à une application cliente de demander des informations ou d'effectuer des opérations sur les ressources exposées par un serveur.

Ces ressources peuvent représenter différents éléments :

• Des utilisateurs.

• Des produits.

• Des commandes.

• Des événements.

• Des articles.

• Des transactions financières.

Prenons l'exemple d'une application de gestion de produits.

Au lieu de connecter directement l'application mobile à la base de données MySQL, on met en place un serveur qui expose plusieurs points d'accès, appelés endpoints.

L'application mobile communique avec ces endpoints pour consulter, créer, modifier ou supprimer des produits.

Le serveur reçoit les demandes, applique les règles métier, interagit avec la base de données et retourne une réponse.

Cette séparation permet à plusieurs applications différentes d'utiliser le même service backend.

2. Comment fonctionne une API REST ?

Le fonctionnement d'une API REST repose principalement sur un modèle client-serveur.

Le client peut être :

• Une application Android ou iOS.

• Un site web développé en JavaScript.

• Une application Flutter.

• Un logiciel de bureau développé avec WinDev.

• Un autre serveur informatique.

Le serveur héberge l'API et assure le traitement des demandes.

Voici le déroulement général d'un échange :

1. Le client envoie une requête HTTP.

Il indique l'adresse de la ressource qu'il souhaite consulter ou modifier, ainsi que la méthode HTTP à utiliser.

2. Le serveur reçoit la requête.

L'API analyse les informations transmises, vérifie les paramètres et contrôle les autorisations lorsque cela est nécessaire.

3. Le serveur exécute le traitement demandé.

Il peut consulter une base de données, enregistrer une nouvelle information, modifier un enregistrement ou supprimer une ressource.

4. Le serveur retourne une réponse.

La réponse contient généralement un code de statut HTTP et des données structurées, souvent au format JSON.

5. Le client exploite le résultat.

L'application cliente interprète les données reçues pour afficher les informations ou mettre à jour son interface.

Exemple concret

Imaginons une application mobile qui souhaite afficher la liste des produits disponibles dans une boutique.

Elle envoie une requête vers :

GET https://api.exemple.com/api/products

Le serveur reçoit la demande, récupère les produits dans sa base de données et retourne une réponse JSON :

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Ordinateur portable",
            "price": 850
        },
        {
            "id": 2,
            "name": "Clavier mécanique",
            "price": 45
        }
    ]
}

L'application mobile peut alors exploiter ces informations pour afficher les produits dans son interface.

Il est important de comprendre que le client ne communique pas directement avec MySQL. C'est le serveur qui contrôle les opérations et protège l'accès aux données.

3. Les principales méthodes HTTP utilisées dans une API REST

Les méthodes HTTP permettent d'indiquer au serveur le type d'opération que le client souhaite effectuer.

Dans une API REST, cinq méthodes sont particulièrement importantes.

GET : récupérer des informations

La méthode GET permet de consulter une ressource sans demander sa modification.

Exemples :

GET /api/products

Récupérer la liste des produits.

GET /api/products/15

Récupérer le produit dont l'identifiant est 15.

POST : créer une nouvelle ressource

La méthode POST permet généralement d'envoyer des données au serveur afin de créer une nouvelle ressource.

Exemple :

POST /api/products

Corps de la requête :

{
    "name": "Souris sans fil",
    "price": 25
}

Le serveur traite les informations et enregistre le nouveau produit.

PUT : remplacer une ressource

La méthode PUT permet de remplacer la représentation complète d'une ressource existante.

Exemple :

PUT /api/products/15

Corps de la requête :

{
    "name": "Souris Bluetooth",
    "price": 30
}

PATCH : modifier partiellement une ressource

Contrairement à PUT, PATCH permet de modifier uniquement certains attributs d'une ressource.

Exemple :

PATCH /api/products/15

Corps de la requête :

{
    "price": 35
}

Seul le prix du produit est modifié.

DELETE : supprimer une ressource

La méthode DELETE permet de demander la suppression d'une ressource.

Exemple :

DELETE /api/products/15

Le serveur traite la demande et supprime le produit concerné, sous réserve des autorisations et règles métier applicables.

À retenir :

• GET : consulter.

• POST : créer.

• PUT : remplacer.

• PATCH : modifier partiellement.

• DELETE : supprimer.

Ces méthodes constituent la base des opérations CRUD (Create, Read, Update, Delete). https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods

4. Comprendre les endpoints et les ressources

Dans une API REST, les adresses sont généralement organisées autour des ressources manipulées.

Un endpoint représente un point d'accès permettant d'interagir avec une ressource ou une collection de ressources.

Prenons l'exemple d'une API de gestion des utilisateurs :

Une bonne convention consiste à utiliser des noms de ressources au pluriel et à laisser la méthode HTTP déterminer l'opération.

Il est également préférable d'éviter des adresses comme :

/api/getUsers
/api/createUser
/api/deleteUser/12

On privilégiera plutôt :

/api/users
/api/users/12

Cette organisation rend les interfaces plus cohérentes et plus faciles à comprendre.

5. Comprendre les codes de réponse HTTP

Lorsqu'une API reçoit une requête, elle doit indiquer au client si l'opération a réussi ou si un problème est survenu.

Pour cela, elle utilise les codes de statut HTTP.

Voici les principaux codes rencontrés dans le développement d'API :

Il est important de choisir correctement ces codes, car ils permettent à l'application cliente de comprendre le résultat d'une opération sans devoir interpréter uniquement le contenu du message.

Par exemple, une application mobile peut afficher un message différent lorsqu'un utilisateur n'est pas authentifié ou lorsqu'un produit demandé n'existe pas. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status

6. Pourquoi le format JSON est-il autant utilisé ?

JSON signifie JavaScript Object Notation.

Il s'agit d'un format léger permettant de représenter des données structurées sous forme de paires clé-valeur et de collections.

Il est particulièrement adapté aux API, car il est facile à produire, à transmettre et à interpréter dans de nombreux langages de programmation.

Exemple :

{
    "id": 25,
    "firstname": "Christian",
    "lastname": "Vulgosing",
    "email": "contact@example.com",
    "active": true
}

Ce même objet peut être interprété par une application Flutter, un site JavaScript, un programme PHP ou un logiciel WinDev.

C'est l'un des grands avantages des API : les applications n'ont pas besoin d'utiliser le même langage de programmation pour échanger des informations.

Pour annoncer qu'une réponse contient du JSON, le serveur utilise généralement l'en-tête HTTP suivant :

Content-Type: application/json; charset=utf-8

De son côté, le client peut préciser qu'il souhaite recevoir ce format avec l'en-tête Accept.

7. Créer sa première API REST avec PHP et MySQL

Passons maintenant à la pratique.

Nous allons construire une petite API de gestion de produits en utilisant PHP et MySQL, sans framework.

L'objectif est de comprendre les mécanismes essentiels : réception des requêtes HTTP, traitement des données, connexion à la base de données et retour des réponses JSON.

7.1. Préparer la base de données

Commençons par créer une base de données appelée api_demo.

Nous allons ensuite créer une table products pour stocker les produits.

CREATE DATABASE api_demo
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;

USE api_demo;

CREATE TABLE products (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(150) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Ajoutons quelques données pour effectuer nos premiers tests :

INSERT INTO products (name, price) VALUES
('Ordinateur portable', 850.00),
('Clavier mécanique', 45.00),
('Souris sans fil', 25.00);

7.2. Organiser le projet

Créons un dossier appelé api-demo dans notre serveur web.

Voici une organisation simple :

api-demo/
│
├── config/
│   └── database.php
│
├── products/
│   └── index.php
│
└── .htaccess

Le fichier database.php contiendra la configuration de connexion à MySQL.

Le fichier products/index.php sera chargé de traiter les différentes requêtes relatives aux produits.

7.3. Configurer la connexion à MySQL

Dans le fichier config/database.php, ajoutons le code suivant :

<?php

$host = "localhost";
$dbname = "api_demo";
$username = "root";
$password = "";

try {

    $pdo = new PDO(
        "mysql:host=$host;dbname=$dbname;charset=utf8mb4",
        $username,
        $password
    );

    $pdo->setAttribute(
        PDO::ATTR_ERRMODE,
        PDO::ERRMODE_EXCEPTION
    );

    $pdo->setAttribute(
        PDO::ATTR_DEFAULT_FETCH_MODE,
        PDO::FETCH_ASSOC
    );

} catch (PDOException $e) {

    error_log($e->getMessage());

    http_response_code(500);

    header("Content-Type: application/json; charset=utf-8");

    echo json_encode([
        "success" => false,
        "message" => "Erreur de connexion à la base de données."
    ]);

    exit;
}

Nous utilisons PDO pour communiquer avec MySQL.

Cette extension permet notamment d'exécuter des requêtes préparées, ce qui aide à prévenir les injections SQL lorsque les paramètres utilisateurs sont correctement liés.

Les identifiants de connexion présentés ici sont uniquement destinés à un environnement local de démonstration. En production, ils doivent être protégés et stockés dans une configuration non accessible publiquement.

7.4. Créer le point d'entrée de l'API

Dans products/index.php, commençons par charger la connexion à la base de données et définir quelques fonctions utilitaires.

<?php

header("Content-Type: application/json; charset=utf-8");

require_once __DIR__ . "/../config/database.php";

/**
 * Retourne une réponse JSON.
 */
function response($status, $data)
{
    http_response_code($status);

    echo json_encode(
        $data,
        JSON_UNESCAPED_UNICODE
    );

    exit;
}

/**
 * Récupère les données JSON envoyées par le client.
 */
function getJsonInput()
{
    $input = json_decode(
        file_get_contents("php://input"),
        true
    );

    if (!is_array($input)) {
        response(400, [
            "success" => false,
            "message" => "Corps JSON invalide."
        ]);
    }

    return $input;
}

// Récupération de la méthode HTTP.
$method = $_SERVER["REQUEST_METHOD"];

// Récupération de l'identifiant éventuel.
$id = isset($_GET["id"])
    ? filter_var($_GET["id"], FILTER_VALIDATE_INT)
    : null;

La fonction response() permet de centraliser le format des réponses JSON.

La fonction getJsonInput() récupère les données envoyées dans le corps de la requête et vérifie qu'elles peuvent être interprétées comme un objet ou un tableau JSON.

Nous pouvons maintenant ajouter les différentes opérations CRUD.

7.5. Consulter la liste des produits (GET)

Ajoutons le traitement de la méthode GET :

if ($method === "GET") {

    if ($id !== null && $id !== false && $id > 0) {

        $stmt = $pdo->prepare(
            "SELECT * FROM products WHERE id = ?"
        );

        $stmt->execute([$id]);

        $product = $stmt->fetch();

        if (!$product) {
            response(404, [
                "success" => false,
                "message" => "Produit introuvable."
            ]);
        }

        response(200, [
            "success" => true,
            "data" => $product
        ]);
    }

    $stmt = $pdo->query(
        "SELECT * FROM products ORDER BY id DESC"
    );

    response(200, [
        "success" => true,
        "data" => $stmt->fetchAll()
    ]);
}

Ce traitement permet deux opérations :

• Sans identifiant, l'API retourne la liste des produits.

• Avec un identifiant valide, elle retourne le produit correspondant.

7.6. Ajouter un produit (POST)

Pour créer un produit, nous allons récupérer les informations JSON envoyées par le client.

if ($method === "POST") {

    $data = getJsonInput();

    $name = trim($data["name"] ?? "");
    $price = $data["price"] ?? null;

    if (
        $name === "" ||
        !is_numeric($price) ||
        !is_finite((float) $price) ||
        (float) $price < 0
    ) {
        response(422, [
            "success" => false,
            "message" => "Nom ou prix invalide."
        ]);
    }

    $stmt = $pdo->prepare(
        "INSERT INTO products (name, price)
         VALUES (?, ?)"
    );

    $stmt->execute([
        $name,
        $price
    ]);

    response(201, [
        "success" => true,
        "message" => "Produit créé avec succès.",
        "data" => [
            "id" => (int) $pdo->lastInsertId(),
            "name" => $name,
            "price" => (float) $price
        ]
    ]);
}

L'API vérifie les données avant de les enregistrer.

Si elles sont valides, le produit est ajouté à la base de données et le serveur retourne le code HTTP 201.

7.7. Modifier un produit (PUT)

La méthode PUT permet ici de remplacer les informations principales d'un produit existant.

if ($method === "PUT") {

    if (!$id || $id < 1) {
        response(400, [
            "success" => false,
            "message" => "Identifiant invalide."
        ]);
    }

    $data = getJsonInput();

    $name = trim($data["name"] ?? "");
    $price = $data["price"] ?? null;

    if (
        $name === "" ||
        !is_numeric($price) ||
        !is_finite((float) $price) ||
        (float) $price < 0
    ) {
        response(422, [
            "success" => false,
            "message" => "Nom ou prix invalide."
        ]);
    }

    $stmt = $pdo->prepare(
        "UPDATE products
         SET name = ?, price = ?
         WHERE id = ?"
    );

    $stmt->execute([
        $name,
        $price,
        $id
    ]);

    if ($stmt->rowCount() === 0) {

        $check = $pdo->prepare(
            "SELECT id FROM products WHERE id = ?"
        );

        $check->execute([$id]);

        if (!$check->fetch()) {
            response(404, [
                "success" => false,
                "message" => "Produit introuvable."
            ]);
        }
    }

    response(200, [
        "success" => true,
        "message" => "Produit mis à jour avec succès."
    ]);
}

Nous vérifions également si le produit existe, y compris lorsque les nouvelles valeurs sont identiques aux anciennes.

7.8. Supprimer un produit (DELETE)

Enfin, ajoutons la suppression :

if ($method === "DELETE") {

    if (!$id || $id < 1) {
        response(400, [
            "success" => false,
            "message" => "Identifiant invalide."
        ]);
    }

    $stmt = $pdo->prepare(
        "DELETE FROM products WHERE id = ?"
    );

    $stmt->execute([$id]);

    if ($stmt->rowCount() === 0) {
        response(404, [
            "success" => false,
            "message" => "Produit introuvable."
        ]);
    }

    response(200, [
        "success" => true,
        "message" => "Produit supprimé avec succès."
    ]);
}

Pour terminer, ajoutons une réponse lorsque la méthode HTTP demandée n'est pas prise en charge :

response(405, [
    "success" => false,
    "message" => "Méthode HTTP non autorisée."
]);

Nous disposons maintenant d'un point d'entrée capable de traiter les cinq opérations principales d'une API CRUD.

7.9. Configurer les URL avec Apache

Pour rendre les adresses plus propres, nous pouvons utiliser un fichier .htaccess.

Dans notre exemple, nous souhaitons pouvoir appeler les ressources avec des URL telles que :

/api/products
/api/products?id=1

Une configuration Apache possible est :

RewriteEngine On

RewriteRule ^api/products/?$ products/index.php [QSA,L]

Cette règle nécessite que le module mod_rewrite soit activé et que les autorisations AllowOverride permettent l'utilisation des fichiers .htaccess.

Dans un environnement de production, il est préférable de placer le point d'entrée public dans un répertoire dédié et de ne pas exposer directement les fichiers de configuration.

8. Comment tester son API REST ?

Une fois notre API créée, nous devons vérifier que chaque endpoint fonctionne correctement.

Plusieurs outils permettent d'envoyer des requêtes HTTP et d'examiner les réponses.

Parmi les plus connus, nous retrouvons :

• Postman : pour créer, organiser et exécuter des requêtes HTTP.

• Insomnia : pour tester et documenter des API.

• cURL : pour effectuer des requêtes directement depuis un terminal.

Voici quelques exemples avec cURL.

Lister les produits :

curl -i https://localhost/api/products

Ajouter un produit :

curl -i -X POST https://localhost/api/products \
-H "Content-Type: application/json" \
-d '{"name":"Écran 24 pouces","price":150}'

Modifier un produit :

curl -i -X PUT "https://localhost/api/products?id=1" \
-H "Content-Type: application/json" \
-d '{"name":"Écran 27 pouces","price":220}'

Supprimer un produit :

curl -i -X DELETE "https://localhost/api/products?id=1"

Pour les tests locaux, remplacez l'adresse par celle de votre environnement, par exemple http://localhost/api/products.

En ajoutant l'option -i, cURL affiche également les en-têtes et le code de statut HTTP retournés par le serveur.

9. Comment sécuriser une API REST ?

Créer une API fonctionnelle est une première étape. La sécuriser est une autre responsabilité tout aussi importante.

Une API mal protégée peut exposer des données confidentielles, permettre des modifications non autorisées ou donner accès à des fonctionnalités réservées à certains utilisateurs.

Voici quelques bonnes pratiques à appliquer.

Utiliser HTTPS

Les échanges entre le client et le serveur doivent être chiffrés. HTTPS protège notamment les données transmises contre leur interception pendant le transport.

Mettre en place une authentification

Les endpoints sensibles doivent vérifier l'identité du client. Une méthode courante consiste à utiliser un jeton d'accès transmis dans l'en-tête Authorization.

Exemple :

Authorization: Bearer VOTRE_TOKEN

Vérifier les autorisations

Être authentifié ne signifie pas avoir le droit d'effectuer toutes les opérations.

L'API doit vérifier que l'utilisateur possède réellement les autorisations nécessaires pour consulter, modifier ou supprimer chaque ressource.

Valider toutes les données reçues

Les données envoyées par le client ne doivent jamais être considérées comme fiables. Il faut vérifier les types, les longueurs, les formats et les règles métier.

Utiliser des requêtes préparées

Les requêtes SQL doivent utiliser des paramètres liés plutôt que d'intégrer directement les données reçues dans les instructions SQL. https://www.php.net/manual/en/pdo.prepare.php

Limiter les requêtes abusives

La mise en place d'une limitation du nombre de requêtes peut aider à prévenir certaines formes d'abus et de surcharge.

Ne jamais exposer les informations sensibles

Les mots de passe, les clés secrètes, les identifiants de connexion et les traces techniques détaillées ne doivent pas apparaître dans les réponses publiques de l'API.

Il faut également désactiver l'affichage des erreurs PHP en production et conserver les détails techniques dans des journaux protégés.

10. Les bonnes pratiques pour concevoir une API professionnelle

Une API ne doit pas seulement fonctionner. Elle doit également être compréhensible, cohérente et facile à faire évoluer.

Quelques principes méritent une attention particulière :

Organiser les ressources

Utiliser des endpoints cohérents et éviter de multiplier les URL inutilement.

Versionner l'API

Lorsqu'une évolution risque de modifier le comportement des clients existants, une version peut être introduite dans l'adresse.

Exemple :

/api/v1/products
/api/v2/products

Prévoir la pagination

Lorsqu'une API doit retourner des milliers d'enregistrements, il est préférable de transmettre les résultats par pages plutôt que de charger toutes les données en une seule réponse.

Exemple :

/api/products?page=1&limit=20

Uniformiser les réponses

Adopter une structure JSON cohérente pour les succès et les erreurs facilite le travail des développeurs qui consomment l'API.

Documenter les endpoints

Une documentation permet de connaître les URL disponibles, les méthodes HTTP, les paramètres attendus, les réponses possibles et les mécanismes d'authentification.

OpenAPI est notamment une solution largement utilisée pour décrire les interfaces HTTP. https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design

Prévoir des tests

Les tests doivent couvrir les cas normaux, les erreurs de validation, les problèmes d'authentification et les comportements inattendus.

11. Pourquoi les API REST sont-elles essentielles dans les applications modernes ?

L'un des grands avantages d'une API REST est la séparation entre le frontend et le backend.

Cette architecture permet de développer plusieurs applications clientes qui utilisent un même serveur.

Prenons l'exemple d'une plateforme de réservation d'événements.

Le même backend peut être utilisé par :

• Une application Android développée avec Flutter.

• Une application iOS.

• Un site web développé avec JavaScript.

• Un logiciel de gestion développé avec WinDev.

• Un outil externe autorisé à communiquer avec la plateforme.

Chaque client utilise les mêmes endpoints pour consulter les événements, gérer les utilisateurs ou effectuer certaines opérations.

Cette organisation évite de dupliquer toute la logique métier dans chaque application.

Elle facilite également la maintenance et permet de faire évoluer les interfaces indépendamment du serveur, à condition de préserver la compatibilité du contrat de l'API.

Conclusion

Les API REST constituent aujourd'hui un élément fondamental de l'architecture des applications modernes.

Elles permettent de faire communiquer différents systèmes, de centraliser les traitements métier et de rendre les données accessibles à plusieurs applications clientes à travers une interface commune.

Comprendre leur fonctionnement ne consiste donc pas uniquement à connaître les méthodes GET, POST, PUT ou DELETE. Il faut également maîtriser les échanges HTTP, la gestion des ressources, les formats de données, les mécanismes d'authentification et les bonnes pratiques de sécurité.

Avec PHP et MySQL, il est tout à fait possible de concevoir une API REST sans framework, en comprenant chaque étape de son fonctionnement.

Une bonne API ne se contente pas de transmettre des données : elle constitue un véritable contrat de communication entre plusieurs systèmes informatiques.

C'est cette capacité à faire collaborer des technologies différentes qui fait des API REST un élément incontournable du développement logiciel.