Les Méthodes HTTP dans REST : Une approche pratique

Dans le cadre du développement d’applications web, les méthodes HTTP jouent un rôle crucial en définissant les actions à réaliser sur les ressources d’une API REST, telles que les tâches dans une application de gestion. Comprendre ces méthodes est essentiel pour interagir efficacement avec les APIs, car elles permettent de personnaliser les requêtes en fonction des besoins. Dans cet article, nous allons explorer ces méthodes en détail et examiner comment elles facilitent la gestion des ressources.

Les méthodes HTTP sont des actions que le client peut effectuer sur les ressources d’une API REST. Chaque méthode a un but spécifique et permet de gérer les ressources de manière cohérente et standardisée.

Récupérer des données avec GET

La méthode GET est utilisée pour consulter des informations. Supposons que vous voulez récupérer uniquement les tâches qui sont marquées comme « complètes ». Vous pourriez ajouter un paramètre à votre requête, comme ceci :

fetch('https://api.example.com/taches?status=complet');

Dans cet exemple, le paramètre status=complet est ajouté à l’URL pour filtrer les résultats. Côté serveur, en PHP, vous récupérerez ce paramètre avec la superglobale $_GET

$status = $_GET['status']; // Récupère la valeur 'complet'

Ensuite, vous pourriez utiliser cette valeur pour ajuster votre requête SQL ou votre logique de traitement.

Créer de nouvelles ressources avec POST

Lorsque vous créez une nouvelle ressource, comme une tâche, vous pouvez passer des paramètres dans le corps de la requête. Par exemple, pour ajouter une nouvelle tâche avec un titre et une description, vous ferez une requête POST

fetch('https://api.example.com/taches', { 
    method: 'POST', 
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: 'Nouvelle tâche', description: 'Faire le ménage' })
});

Les paramètres title et description sont envoyés dans le corps de la requête. Côté serveur, en PHP, vous récupérerez ces données via la superglobale $_POST

$title = $_POST['title']; // 'Nouvelle tâche'
$description = $_POST['description']; // 'Faire le ménage'

Pour les requêtes AJAX utilisant fetch, il est souvent plus simple de décoder les données JSON comme ceci

$data = json_decode(file_get_contents('php://input'), true);
$title = $data['title'];
$description = $data['description'];

Mettre à jour une ressource existante avec PUT

La méthode PUT permet de mettre à jour des ressources existantes. Disons que vous voulez changer le statut d’une tâche existante avec l’identifiant 1. Voici comment passer les paramètres avec fetch

fetch('https://api.example.com/taches/1', { 
    method: 'PUT', 
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: 'en cours' })
});

Ici, le paramètre status est passé dans le corps de la requête pour mettre à jour l’état de la tâche. Contrairement à POST, où les données sont récupérées via la superglobale $_POST, avec PUT, les données ne sont pas automatiquement placées dans cette superglobale. Côté PHP, vous devez utiliser le flux php://input pour lire les données brutes envoyées dans le corps de la requête. Vous pouvez ensuite les décoder et les traiter ainsi

// Lire les données brutes du corps de la requête PUT
$putData = file_get_contents('php://input');

// Convertir les données JSON en tableau associatif
$data = json_decode($putData, true);

// Récupérer le paramètre 'status'
$status = $data['status'] ?? null;

Avec cette approche, vous pouvez mettre à jour des champs spécifiques dans votre base de données ou autre stockage.

Supprimer une ressource avec DELETE

Pour supprimer une ressource, comme une tâche spécifique, vous utiliserez la méthode DELETE. Par exemple, pour supprimer la tâche avec l’identifiant 1 et peut-être un autre paramètre de sécurité, voici comment structurer la requête

fetch('https://api.example.com/taches/1', { 
    method: 'DELETE',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ confirmation: 'oui' })
});

Dans cet exemple, le paramètre confirmation est envoyé dans le corps de la requête DELETE pour s’assurer que l’action de suppression est bien intentionnelle. En PHP, la récupération des données envoyées dans une requête DELETE (ou PUT) ne se fait pas via les superglobales habituelles comme $_POST, mais plutôt à l’instar de PUT, en lisant directement les données brutes à partir du flux php://input. Voici comment vous pouvez le faire

// Lire les données brutes du corps de la requête DELETE
$inputData = file_get_contents('php://input');

// Convertir les données JSON en tableau associatif
$data = json_decode($inputData, true);

// Récupérer le paramètre 'confirmation' en vérifiant qu'il est bien présent
$confirmation = $data['confirmation'] ?? null;

if ($confirmation === 'oui') {
    // Procéder à la suppression de la tâche
    // Code pour supprimer la tâche...
} else {
    // Gérer le cas où la confirmation n'est pas donnée
    // Code pour gérer l'absence de confirmation...
}

Cette méthode garantit que seules les requêtes valides et intentionnelles aboutissent à la suppression d’une ressource

Ces méthodes fondamentales sont la pierre angulaire des opérations CRUD (Créer, Lire, Mettre à jour, Supprimer) qui sont essentielles à toute application RESTful.

Atelier Pratique : Plongez dans le REST CRUD

Après avoir exploré les fondements théoriques des méthodes HTTP telles que GET, POST, PUT et DELETE, il est essentiel de comprendre comment ces concepts se traduisent dans des applications concrètes. En effet, maîtriser ces méthodes est un prérequis pour construire des services web efficaces. Avant de nous plonger dans d’autres méthodes moins courantes comme TRACE ou PATCH, nous vous encourageons à consulter notre article « Mise en place d’une API RESTful CRUD« . Cet article vous guidera dans l’implémentation pratique de ces méthodes, vous permettant ainsi d’appliquer vos connaissances théoriques et d’approfondir votre compréhension des APIs RESTful.

D’autres méthodes HTTP et leur utilité en REST

En plus des méthodes HTTP couramment utilisées dans les API REST telles que GET, POST, PUT, et DELETE, il existe d’autres méthodes HTTP avec des usages spécifiques. Bien que moins fréquentes dans les API RESTful, elles jouent un rôle important dans certaines situations.

HEAD

La méthode HEAD est très similaire à GET, mais ne retourne que les en-têtes de la réponse, sans le corps du message. Cela peut être utile pour vérifier l’existence d’une ressource ou pour obtenir des métadonnées sans télécharger l’intégralité de son contenu. Par exemple, si vous souhaitez vérifier si un document existe sur un serveur sans le télécharger et obtenir des informations, vous pouvez envoyer une requête HEAD

fetch('https://api.example.com/documents/rapport.pdf', { 
    method: 'HEAD'
})
.then(response => {
    console.log('Content-Type:', response.headers.get('Content-Type'));
    console.log('Content-Length:', response.headers.get('Content-Length'));
});

Côté serveur, vous ne devez pas traiter la méthode HEAD différemment de GET, sauf pour ne pas envoyer de corps de réponse. Vous pouvez ajouter une condition pour vérifier la méthode

if ($_SERVER['REQUEST_METHOD'] === 'HEAD') {
    // Envoi seulement des en-têtes, pas de corps
    header('Content-Type: application/pdf');
    header('Content-Length: ' . filesize('documents/rapport.pdf'));
}

OPTIONS

La méthode OPTIONS est utilisée pour découvrir les méthodes HTTP supportées par le serveur pour une ressource donnée. C’est souvent utilisé pour vérifier les permissions CORS. Voir notre article CORS ou la Gestion des Requêtes Cross-Origin.

fetch('https://api.example.com/taches/1', { 
    method: 'OPTIONS'
})
.then(response => response.headers.forEach((value, name) => console.log(`${name}: ${value}`)));

Côté serveur, vous pouvez répondre avec les méthodes autorisées en utilisant les en-têtes appropriés

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE');
    header('Access-Control-Allow-Headers: Content-Type');
    exit;
}

CONNECT

La méthode CONNECT est utilisée pour établir un tunnel HTTP, souvent pour des connexions sécurisées via un proxy. Elle n’est pas typiquement utilisée dans les APIs REST.

// `CONNECT` n'est pas utilisé directement en JavaScript côté client

Vous ne traitez généralement pas les requêtes CONNECT dans un contexte REST. Les serveurs proxy et les serveurs de niveau inférieur gèrent cette méthode.

Supposons que vous souhaitiez établir une connexion HTTPS à un serveur web via un proxy HTTP. Vous utiliseriez la méthode CONNECT pour demander au proxy d’ouvrir un tunnel sécurisé vers le serveur cible. Voici comment vous formuleriez la requête HTTP pour établir ce tunnel

CONNECT www.example.com:443 HTTP/1.1
Host: www.example.com

Où et Comment Envoyer Ce Code ?

Serveur Proxy : La méthode CONNECT est généralement utilisée par un serveur proxy. Vous ne l’envoyez pas directement depuis un script JavaScript ou PHP, mais vous configurez un serveur proxy pour gérer ces requêtes. Vous pouvez utiliser des outils comme curl pour tester ce comportement, ou configurer un proxy qui gère les requêtes CONNECT.

Utilisation Pratique : En pratique, les clients configurent souvent leurs navigateurs ou applications pour utiliser un proxy qui gère automatiquement ces requêtes. Pour des tests ou des démonstrations, vous pouvez utiliser des outils de ligne de commande comme curl

curl -x http://proxyserver:port -L --proxy-tunnel https://www.example.com

Dans cet exemple, curl envoie la requête CONNECT via le proxy spécifié et établit le tunnel vers www.example.com.

Serveur Proxy PHP : Si vous êtes responsable de la configuration d’un serveur proxy ou d’un service proxy en PHP, vous écririez du code pour gérer les requêtes CONNECT. Cela impliquerait d’utiliser des bibliothèques réseau en PHP, comme montré dans l’exemple de code pour un serveur proxy de base en Node.js.

En résumé, la méthode CONNECT est gérée par le serveur proxy ou des outils réseau pour établir des tunnels sécurisés. Vous ne l’envoyez pas directement depuis les scripts côté client, mais vous pouvez tester ou configurer des environnements de développement en utilisant des outils comme curl ou en configurant des serveurs proxy.

TRACE

La méthode TRACE est utilisée pour le débogage en renvoyant la requête reçue par le serveur. Elle est rarement utilisée en production en raison des risques de sécurité.

fetch('https://api.example.com/taches/1', { 
    method: 'TRACE'
})
.then(response => response.text().then(text => console.log(text)));

Pour traiter les requêtes TRACE, vous pouvez renvoyer la requête exacte

if ($_SERVER['REQUEST_METHOD'] === 'TRACE') {
    header('Content-Type: text/plain');
    echo file_get_contents('php://input');
}

PATCH

La méthode PATCH permet de mettre à jour partiellement une ressource. Elle est utile pour modifier seulement certaines parties d’une ressource sans la remplacer entièrement.

fetch('https://api.example.com/taches/1', { 
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: 'completed' })
})
.then(response => response.json())
.then(data => console.log(data));

Côté serveur, vous lisez les données de la requête et appliquez les modifications nécessaires

if ($_SERVER['REQUEST_METHOD'] === 'PATCH') {
    $inputData = file_get_contents('php://input');
    $data = json_decode($inputData, true);
    
    // Supposons que vous avez une fonction pour mettre à jour la tâche
    $status = $data['status'] ?? null;
    if ($status) {
        // Mettre à jour la tâche en base de données
        // Exemple : updateTaskStatus(1, $status);
    }
    
    echo json_encode(['status' => 'success']);
}

PATCH peut sembler similaire à PUT, mais alors que PUT remplace entièrement une ressource existante avec les nouvelles données fournies, PATCH ne modifie que les parties spécifiques de la ressource.

Ces exemples montrent comment chaque méthode HTTP peut être utilisée dans des contextes spécifiques et comment elles peuvent être traitées côté serveur en PHP. En comprenant ces méthodes, vous pouvez concevoir des APIs RESTful plus robustes et adaptées à divers besoins.

Conclusion

Pour une compréhension plus complète de la manière dont ces méthodes s’intègrent dans le cadre plus large de REST, nous vous invitons à lire notre article précédent sur les concepts fondamentaux de REST.

En résumé, les méthodes HTTP sont des outils puissants qui permettent de gérer les ressources d’une API REST de manière standardisée et efficace. En les comprenant et en les appliquant correctement, vous serez en mesure de créer des services web robustes et faciles à maintenir.