Exemple : récupérer des informations depuis une API publique

Etape 1 : Choisir une API et définir notre objectif

Pour cet exemple, nous allons utiliser une API publique simple et qui ne nécessite pas de clé d'authentification : Open Library. C'est une base de données ouverte de livres. Leur API nous permet de rechercher des informations sur des livres, des auteurs, etc.

Notre objectif est simple mais concret : écrire un script qui demande à l'utilisateur le nom d'un auteur, interroge l'API Open Library pour trouver les livres de cet auteur, et affiche les cinq premiers résultats.

L'endpoint que nous allons utiliser est celui de la recherche : https://openlibrary.org/search.json. Nous devrons lui passer un paramètre de recherche, par exemple ?author=George+Orwell pour chercher les livres de George Orwell.

Etape 2 : Préparer le projet avec Bundler et HTTParty

Comme pour tout projet structuré, nous commençons par configurer notre environnement. Créez un dossier pour ce projet et, à l'intérieur, créez un fichier Gemfile et un fichier pour notre script, book_finder.rb.

Dans votre Gemfile, ajoutez la gem httparty :

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

gem 'httparty'

Ensuite, dans votre terminal, installez la dépendance :

$ bundle install

Votre projet est maintenant prêt. Nous avons HTTParty à notre disposition pour effectuer les requêtes web.

Etape 3 : Ecrire le script pour interroger l'API

Ouvrons notre fichier book_finder.rb. Nous allons commencer par charger les bibliothèques nécessaires, définir l'URL de base de l'API et demander à l'utilisateur le nom de l'auteur.

Ensuite, nous utiliserons HTTParty.get pour envoyer la requête. Notez comment nous passons les paramètres de recherche (ici, le nom de l'auteur) via une option query. HTTParty se chargera de formater correctement l'URL pour nous (en ajoutant ?author=...).

# book_finder.rb
require 'httparty'

# L'URL de base de l'API de recherche
BASE_URL = 'https://openlibrary.org/search.json'

puts "Quel auteur souhaitez-vous rechercher ?"
author_name = gets.chomp

puts "Recherche des livres de #{author_name}..."

# Envoi de la requête GET avec un paramètre de recherche 'author'
response = HTTParty.get(BASE_URL, query: { author: author_name })

# Pour l'instant, affichons juste le code de statut pour vérifier
puts "Réponse reçue avec le statut : #{response.code}"

A ce stade, vous pouvez déjà exécuter le script. Si vous entrez "George Orwell", il devrait afficher Réponse reçue avec le statut : 200, confirmant que la communication avec l'API a réussi.

Etape 4 : Analyser la réponse JSON et afficher les résultats

Maintenant que nous recevons une réponse, nous devons l'exploiter. Comme nous l'avons appris, HTTParty parse automatiquement le JSON pour nous dans response.parsed_response. La structure d'une réponse de l'API Open Library ressemble à ceci : {"numFound": 1234, "docs": [ { "title": "..." }, { "title": "..." } ] }.

Les livres se trouvent donc dans un tableau (Array) sous la clé "docs". Nous allons vérifier que la requête a réussi (code 200), extraire ce tableau, et itérer sur les cinq premiers éléments pour afficher leur titre.

Complétons notre script book_finder.rb :

require 'httparty'

BASE_URL = 'https://openlibrary.org/search.json'

puts "Quel auteur souhaitez-vous rechercher ?"
author_name = gets.chomp

puts "Recherche des livres de #{author_name}...\n"

response = HTTParty.get(BASE_URL, query: { author: author_name })

if response.code == 200
  # On accède directement au Hash parsé
  results = response.parsed_response

  # On récupère le tableau de livres sous la clé 'docs'
  books = results['docs']

  if books.empty?
    puts "Aucun livre trouvé pour cet auteur."
  else
    puts "Voici les 5 premiers livres trouvés :"
    # On prend les 5 premiers avec .first(5) et on itère dessus
    books.first(5).each do |book|
      puts "- #{book['title']}"
    end
  end
else
  puts "Une erreur est survenue. Code de statut : #{response.code}"
end

Etape 5 : Exécuter le script complet et observer le résultat

Votre script est maintenant complet. Exécutez-le depuis votre terminal :

$ ruby book_finder.rb

Le programme vous posera une question. Essayez avec "J.R.R. Tolkien" :

Quel auteur souhaitez-vous rechercher ?
J.R.R. Tolkien
Recherche des livres de J.R.R. Tolkien...

Voici les 5 premiers livres trouvés :
- The Hobbit
- The Lord of the Rings
- The fellowship of the ring
- The two towers
- The Return of the King

Félicitations ! Vous venez de créer une application Ruby qui dialogue avec le monde extérieur. Cet exemple met en pratique tout ce que nous avons vu : la gestion de dépendances avec Bundler, l'envoi de requêtes HTTP avec HTTParty, la gestion de la réponse et le parsing de données JSON pour les utiliser dans notre logique. C'est une base solide sur laquelle vous pouvez maintenant construire des projets bien plus complexes.