Comment installer et utiliser la gem HTTParty

Pourquoi utiliser une gem pour les requêtes HTTP ?

Ruby dispose d'une bibliothèque standard pour effectuer des requêtes HTTP, appelée Net::HTTP. Bien qu'elle soit puissante et complète, sa syntaxe peut être verbeuse et peu intuitive pour des opérations courantes. Vous vous retrouveriez à écrire beaucoup de code de configuration pour une simple requête.

C'est là que des gems comme HTTParty entrent en jeu. HTTParty est une surcouche à Net::HTTP qui a pour unique but de rendre l'envoi de requêtes et la gestion des réponses aussi simples et lisibles que possible. Elle masque la complexité sous-jacente et vous fournit une interface élégante. Utiliser HTTParty, c'est choisir un outil spécialisé qui vous fera gagner du temps et rendra votre code plus compréhensible.

Etape 1 : Installer HTTParty avec Bundler

Comme pour toute dépendance externe dans un projet Ruby moderne, la meilleure façon d'installer et de gérer HTTParty est d'utiliser Bundler. Cela garantit que la version de la gem est verrouillée et cohérente pour tous les développeurs.

Ouvrez votre Gemfile à la racine de votre projet et ajoutez la ligne suivante :

# Gemfile
source 'https://rubygems.org'

gem 'httparty'

Ensuite, ouvrez votre terminal, naviguez jusqu'au répertoire de votre projet et exécutez la commande d'installation de Bundler :

$ bundle install

Bundler va télécharger HTTParty (et ses propres dépendances, le cas échéant) et mettre à jour votre Gemfile.lock. La gem est maintenant installée et prête à être utilisée dans votre projet.

Etape 2 : Envoyer votre première requête GET

L'utilisation de HTTParty est d'une simplicité déconcertante. Pour envoyer une requête GET, il vous suffit d'appeler la méthode de classe .get sur le module HTTParty, en lui passant l'URL de l'endpoint que vous souhaitez interroger.

Créons un script simple qui interroge une API de test publique, JSONPlaceholder, qui renvoie des données factices.

# api_client.rb
require 'httparty'

# L'URL de l'API que nous voulons interroger
url = 'https://jsonplaceholder.typicode.com/posts/1'

# On envoie la requête GET. HTTParty s'occupe de tout.
response = HTTParty.get(url)

# On affiche le corps de la réponse
puts response.body

Si vous exécutez ce script (ruby api_client.rb), vous verrez s'afficher dans votre terminal une chaîne de caractères au format JSON. C'est le corps de la réponse renvoyée par l'API.

Comment analyser et utiliser la réponse ?

L'objet response retourné par HTTParty est bien plus qu'une simple chaîne de caractères. Il contient toutes les informations de la réponse HTTP, accessibles via des méthodes intuitives :

• response.code : Retourne le code de statut HTTP (ex: 200, 404). C'est essentiel pour vérifier si la requête a réussi.
• response.body : Le corps brut de la réponse, sous forme de chaîne de caractères (ce que nous avons affiché plus haut).
• response.headers : Les en-têtes de la réponse, sous forme de Hash.
• response.parsed_response : C'est ici que la magie opère ! Si la réponse contient l'en-tête Content-Type: application/json, HTTParty va automatiquement parser le corps JSON pour vous et le transformer en un Hash ou un Array Ruby.

Améliorons notre script pour utiliser cette fonctionnalité et vérifier le statut de la requête :

require 'httparty'

url = 'https://jsonplaceholder.typicode.com/posts/1'
response = HTTParty.get(url)

if response.code == 200
  # On utilise .parsed_response qui est déjà un Hash Ruby !
  post_data = response.parsed_response
  puts "Titre du post : #{post_data['title']}"
else
  puts "La requête a échoué avec le code : #{response.code}"
end

Ce code est beaucoup plus robuste. Il vérifie d'abord que la requête a réussi, puis il accède directement aux données parsées comme à un Hash classique. Vous n'avez même pas besoin d'écrire JSON.parse vous-même ! C'est le principal avantage de HTTParty.