⚠️ Avant de commencer cette quête, nous te conseillons de terminer celle-ci :

Dans les quêtes précédentes, tu as découvert comment construire une API avec Express, en utilisant une base de données MySQL et comment tester tes routes avec Postman.

Tu as également créé des routes avec Express, te permettant d'effectuer différentes opérations de base de données : sélectionner (GET), insérer (POST), mettre à jour (PUT) et supprimer (DELETE).

Cette quête se concentre sur le traitement détaillé des requêtes GET. Cela permettra de revenir sur les objets Request (req) et Response (res) utilisés dans les HANDLERS de route Express.

🤓 Dans cette quête, tu vas apprendre à :

✅ Différencier deux types de requêtes GET ✅ Comprendre comment utiliser req.params et req.query ✅ Utiliser les paramètres d'URL pour créer une requête SQL

🤓 Rappels sur les APIs REST

Les API REST (ou RESTful) fournissent au client des ressources. Par exemple, dans les quêtes Express précédentes, tu as fourni des ressources "users" et "movies".

Chaque ressource est identifiée par une URL unique. L'URL http://fakebook.com/users/10 identifie un utilisateur avec l'id 10.

L'envoi d'une requête avec une méthode HTTP spécifique au serveur entraîne une opération correspondante dans la base de données. C'est ce qu'on appelle le CRUD (Create-Read-Update-Delete), et tu peux trouver des équivalents ici :

La définition de CRUD sur Wikipedia est assez concise et accessible : suis le lien ci-dessous pour en savoir plus.

🤼 Deux types de requête GET

Bien que le terme CRUD soit largement utilisé, il ignore une différence importante entre deux types de requêtes GET :

• Une application peut avoir besoin de récupérer un ensemble de ressources, par exemple, une liste de films. Pour cela, tu peux utiliser l'URL localhost:5000/api/movies.
• Elle peut, au contraire, nécessiter de récupérer une ressource, par exemple un seul film. Dans ce cas, tu pourrais ajouter un / suivi d'une valeur pour identifier précisément la ressource ciblée. Cela peut être son id, comme dans http://localhost:5000/api/movies/2.

🤷🏻‍♀️ Pourquoi deux types de requêtes GET?

Si tu peux récupérer une liste directement, en quoi cela t'aiderait de récupérer une seule ressource ?

L'une des motivations est de maintenir la cohérence de l'API REST.

Dans une API REST, des routes doivent exister pour permettre la mise à jour ou la suppression d'une ressource. Tu reverras (ou as déjà vu ?) cela dans d'autres quêtes :

Cela permet à ton API de gérer les requêtes PUT et DELETE sur /api/movies/:id. Il est logique d'avoir également la possibilité de lire (GET) une ressource sur la même URL.

L'autre motivation est de minimiser la quantité de données transférées sur le réseau, et donc le temps de transfert. C'est un critère de performance important, surtout pour les connexions lentes !

Le transfert d'une liste de ressources peut prendre beaucoup de temps, surtout s'il y a beaucoup d'éléments et/ou si chaque élément a un grand nombre de champs. Dans l'API, il est possible de remédier à ce problème de la manière suivante :

• En ne renvoyant qu'une partie de la liste complète ("pagination").
• Renvoyer uniquement les champs "principaux" de chaque ressource.

Le transfert d'une seule ressource est moins gourmand en bande passante. Nous pouvons donc nous permettre d'inclure plus de champs dans la réponse.

Pour illustrer cela, interroge les deux URL suivantes de l'API GitHub (via Postman ou ton navigateur) :

• https://api.github.com/users?since=100000 - Renvoie une liste d'utilisateurs (tableau d'objets).
• https://api.github.com/users/tj - Renvoie un utilisateur (objet) à l'aide de son identifiant (pour information, cet utilisateur est le créateur d'Express).

Tu peux remarquer les éléments suivants concernant les données renvoyées :

• Le tableau renvoyé par la première route est limité à 30 profils d'utilisateurs (imagine le temps qu'il faudrait pour récupérer des millions de profils enregistrés !)
• L'objet retourné par la deuxième route contient des champs tels que email, location, bio... absents des résultats de la première route.

Tu peux également remarquer que ces deux URL sont configurables, mais pas de la même manière :

• Dans la première URL, une chaîne est passée avec des paramètres d'URL ou query string (?since=100000). Elle permet de filtrer l'ensemble des résultats. La query string ne fait pas partie du path de l'URL (https://api.github.com/users) et est généralement facultative. Dans Express, tu peux récupérer ces données via l'objet req.query.
• Dans la deuxième URL, l'identifiant unique de la ressource est inclus dans le path de l'URL. Dans Express, ce type de paramètre est récupéré via l'objet req.params.

Ces deux façons de récupérer des variables via l'URL sont documentées dans l'article ci-dessous.

🍿 Retour sur l'application des films

Tu vas modifier l'application pour ajouter la possibilité de filtrer la liste des films, via la query string.

🔎 Implementer un filtre

Nous allons utiliser un paramètre d'URL non obligatoire (par exemple, ?color=1) pour filtrer les résultats.

Cela signifie que le même HANDLER pourra être utilisé de deux manières. Par défaut, la requête GET /api/movies conduira à la requête SQL select * from movies, sans aucune autre valeur transmise à database.query(). Ceci est couvert par notre code actuel :

const getMovies = (req, res) => {
  database
    .query("select * from movies")
    .then(([movies]) => {
      res.json(movies);
    })
    .catch((err) => {
      console.error(err);
      res.status(500).send("Error retrieving data from database");
    });
};

Si req.query.color est défini, tu devrais modifier la requête SQL en select * from movies where color = ?, et passer la valeur de la couleur dans un tableau comme second paramètre à database.query(). Essaie d'adapter le code pour ajouter cette fonctionnalité. Quelques conseils :

• Tu dois d'abord déclarer des variables pour stocker la chaîne SQL et le tableau avec les valeurs SQL. Tu peux les appeler sql et sqlValues.
• Par défaut, sql contiendra select * from movies et sqlValues sera un tableau vide.
• Si req.query.color est défini, sql contiendra select * from movies where color = ? et sqlValues contiendra le paramètre de couleur.
• Une fois que sql et sqlValues sont prêts, tu peux les passer à database.query().

Afficher la solution|||javascript|||Tu as des doutes sur comment faire ?|||0|||Masquer
const getMovies = (req, res) => {
  let sql = "select * from movies";
  const sqlValues = [];

  if (req.query.color != null) {
    sql += " where color = ?";
    sqlValues.push(req.query.color);
  }

  database
    .query(sql, sqlValues)
    .then(([movies]) => {
      res.json(movies);
    })
    .catch((err) => {
      console.error(err);
      res.status(500).send("Error retrieving data from database");
    });
};

Maintenant que tu en es là, pourquoi ne pas pimenter un peu les choses ? Essaie d'ajouter un paramètre max_duration pour filtrer les films avec une duration inférieure ou égale à la valeur dans la query string. Fais-le étape par étape : essaie d'abord de gérer max_duration sans te soucier du paramètre color. Ton objectif est de répondre à des requêtes telles que GET /api/movies/?max_duration=150.

Afficher la solution|||javascript|||Tu as des doutes sur comment faire ?|||0|||Masquer
let sql = "select * from movies";
const sqlValues = [];

if (req.query.color != null) {
  sql += " where color = ?";
  sqlValues.push(req.query.color);
}
if (req.query.max_duration != null) {
  sql += " where duration <= ?";
  sqlValues.push(req.query.max_duration);
}

Essaie maintenant de gérer à la fois max_duration et color. Ton objectif est maintenant de répondre à des requêtes telles que GET /api/movies/?max_duration=150&color=0.

Afficher la solution|||javascript|||Tu as des doutes sur comment faire ?|||0|||Masquer
let sql = "select * from movies";
const sqlValues = [];

if (req.query.color != null) {
  sql += " where color = ?";
  sqlValues.push(req.query.color);

  if (req.query.max_duration != null) {
    sql += " and duration <= ?";
    sqlValues.push(req.query.max_duration);
  }
} else if (req.query.max_duration != null) {
  sql += " where duration <= ?";
  sqlValues.push(req.query.max_duration);
}

Ça commence à se compliquer. Imagine si tu dois gérer encore plus de paramètres : tu auras des tonnes de "if" imbriqués pour gérer tous les cas. Si tu n'as pas peur de voir du code plus avancé, celui caché ci-dessous s'attaque à ce problème : ouvre à tes risques et périls ;)

À fond, montre moi !|||javascript|||Tu veux vraiment faire ça ?|||0|||Masquer
const getMovies = (req, res) => {
  const initialSql = "select * from movies";
  const where = [];

  if (req.query.color != null) {
    where.push({
      column: "color",
      value: req.query.color,
      operator: "=",
    });
  }
  if (req.query.max_duration != null) {
    where.push({
      column: "duration",
      value: req.query.max_duration,
      operator: "<=",
    });
  }

  database
    .query(
      where.reduce(
        (sql, { column, operator }, index) =>
          `${sql} ${index === 0 ? "where" : "and"} ${column} ${operator} ?`,
        initialSql
      ),
      where.map(({ value }) => value)
    )
    .then(([movies]) => {
      res.json(movies);
    })
    .catch((err) => {
      console.error(err);
      res.status(500).send("Error retrieving data from database");
    });
};

404 ?

A partir de là, si tu GET /api/movies/?max_duration=0, tu obtiendras un tableau vide. Si tu vérifies le statut de la requête dans les outils de développement du navigateur ou dans Postman, tu verras que tu obtiens un statut 200. Mais ton serveur ne devrait-il pas renvoyer un 404, comme la route pour obtenir un film alors que le film n'existe pas ?

Eh bien, pas vraiment. Bien que la question soit discutable, la grande majorité considère qu'il est plus approprié de retourner un code 200 qu'un code 404 lors d'une requête qui produit un tableau vide. Une raison est donnée dans cet discussion sur StackOverflow, qui pose la question : [Une API RESTful doit-elle renvoyer un 404 pour les tableaux d'objets ?] (https://stackoverflow.com/questions/6045895/should-a-restful-api-return-404-for-arrays-of-objects).

En résumé :

• Une ressource (au singulier) est considérée comme existante (200), ou non existante (404).
• Mais une collection (autre nom donné à une liste) existe toujours, même si elle est vide : on retourne donc toujours le code 200.

💪 Challenge

GET me the users

Ajoute deux filtres pour la route GET /api/users existant :

• si un paramètre language est fourni dans l'URL (?language=English), ne renvoie que les locuteurs de cette langue.
• si un paramètre city est fourni dans l'URL (?city=Paris), ne renvoie que les utilisateurs dont la ville correspond au paramètre.

Publie ton application améliorée sur GitHub et partage l'URL ici.

🧐 Critères de validation

• [ ] La route renvoyant une liste d'utilisateurs les renvoie tous si aucun paramètre n'est passé via l'URL.
• [ ] Sinon, elle retourne une liste filtrée selon le paramètre de requête language ou city.
• [ ] (bonus) Si les paramètres language et city sont tous les 2 fournis, les éléments renvoyés doivent répondre aux deux conditions de filtrage.
• [ ] GET api/users renvoie un statut 200 même si la liste est vide.

==$==

Ce que tu devrais avoir dans :

// ...

const getUsers = (req, res) => {
  const initialSql = "select * from users";
  const where = [];

  if (req.query.city != null) {
    where.push({
      column: "city",
      value: req.query.city,
      operator: "=",
    });
  }
  if (req.query.language != null) {
    where.push({
      column: "language",
      value: req.query.language,
      operator: "=",
    });
  }

  database
    .query(
      where.reduce(
        (sql, { column, operator }, index) =>
          `${sql} ${index === 0 ? "where" : "and"} ${column} ${operator} ?`,
        initialSql
      ),
      where.map(({ value }) => value)
    )
    .then(([users]) => {
      res.json(users);
    })
    .catch((err) => {
      console.error(err);
      res.status(500).send("Error retrieving data from database");
    });
};

// ...

// ...

const getMovies = (req, res) => {
  const initialSql = "select * from movies";
  const where = [];

  if (req.query.color != null) {
    where.push({
      column: "color",
      value: req.query.color,
      operator: "=",
    });
  }
  if (req.query.max_duration != null) {
    where.push({
      column: "duration",
      value: req.query.max_duration,
      operator: "<=",
    });
  }

  database
    .query(
      where.reduce(
        (sql, { column, operator }, index) =>
          `${sql} ${index === 0 ? "where" : "and"} ${column} ${operator} ?`,
        initialSql
      ),
      where.map(({ value }) => value)
    )
    .then(([movies]) => {
      res.json(movies);
    })
    .catch((err) => {
      console.error(err);
      res.status(500).send("Error retrieving data from database");
    });
};

// ...