Comment faire une requête API en HTTP ?

Pour utiliser une application disposant d’une API et disponible sur un serveur, on formule une requête auprès de l’API. Cette requête est formulée en HTTP, et contient les informations nécessaires pour que la réponse transmise en retour corresponde à la demande.

La requête est structurée en quatre parties : la méthode, la route, le header et le body.

Le protocole HTTP 

Le protocole HTTP (Hypertext Transfer Protocol) est au fondement de la communication sur le World Wide Web. Il s’agit d’un protocole basé sur le modèle client-serveur et permettant l’échange de ressources entre un client (généralement un navigateur web) et un serveur web.

La communication via HTTP est initiée par le client, qui soumet une requête HTTP au serveur. Le serveur, après traitement de la requête, retourne une réponse HTTP au client.

Le protocole HTTP obéit à deux caractéristiques qui font sa particularité : 

Tout d’abord, il est sans état (stateless), c’est-à-dire que chaque requête est traitée indépendamment des autres.  Ainsi, aucune information concernant les requêtes précédentes n’est conservée. De plus, le protocole est également basé sur du texte : Les requêtes et les réponses HTTP sont principalement composées de texte, ce qui facilite leur inspection et leur débogage.

Comment formuler la requête ? 

Une requête HTTP est structurée en plusieurs composants :

La Méthode HTTP

La méthode indique le type de requête, c’est-à-dire l’action que le client souhaite que le serveur exécute sur la ressource identifiée. Quelques exemples : 

• GET : Récupérer une ressource 
• POST : Créer une nouvelle ressource
• PUT : modifier partiellement une ressource
• DELETE : supprimer une ressource

La route

La route spécifie le chemin à effectuer pour accéder à la ressource-cible sur le serveur.

Par exemple, si l’URL de base d’une API de gestion de livres est https://api.example.com/v1/, les routes pourraient être :

/books : pour accéder à la liste de tous les livres.

/books/123 : pour accéder au livre dont l’identifiant est 123.

/authors/456/books : pour accéder à la liste des livres de l’auteur dont l’identifiant est 456.

En combinant la méthode HTTP et la route, on définit précisément l’opération demandée et la ressource sur laquelle elle doit être appliquée. 

Le header 

Le header HTTP fournit des informations supplémentaires sur la requête elle-même ou sur le client. Il permet d’ajouter du contexte ou des instructions pour le serveur. Voici quelques exemples d’informations couramment présentes dans les headers :

• Authentification : Les données d’authentification, comme les tokens ou les identifiants et mots de passe, sont souvent incluses dans les headers pour permettre au client d’accéder à des ressources protégées par une authentification.
• Gestion des cookies : Étant donné que le protocole HTTP est stateless, des cookies sont utilisés pour maintenir l’état de la session entre plusieurs requêtes. Ils sont donc transmis dans les headers
• Format de la réponse attendue : Le client peut spécifier le format de réponse qu’il préfère en utilisant l’en-tête Accept. Par exemple, Accept: application/json indique que le client préfère recevoir la réponse au format JSON.
• Type de contenu de la requête : Lorsque la requête contient un corps (par exemple, avec les méthodes POST ou PUT), l’en-tête Content-Type indique le format des données envoyées (par exemple, Content-Type: application/json si les données sont au format JSON, Content-Type: application/x-www-form-urlencoded pour les données de formulaire).
• Informations sur le client : L’en-tête User-Agent fournit des informations sur le navigateur ou l’application cliente qui effectue la requête.

En somme, les headers sont essentiels pour configurer la requête et s’assurer que le serveur comprend le contexte et les attentes du client.

Le body

Le body contient toutes les informations liées au contexte de la requête. 

Par exemple, si un client souhaite créer un nouvel utilisateur, le body de la requête POST vers une route comme /users pourrait contenir les informations de l’utilisateur au format JSON :

JSON

{

    « username »: « nouveau_utilisateur »,

    « email »: « nouvel_utilisateur@exemple.com »,

    « password »: « motdepasse »

}

H2 Réponses du serveur en protocole HTTP

Lorsque la requête est envoyée, l’API répond avec des codes HTTP. Par exemple, le code 404 indique que la ressource n’existe pas. Certaines réponses contiennent également un body. 

Ici, le client demande à récupérer une liste d’articles, la réponse contient donc un body avec la liste des articles demandés, en format JSON.