Les paramètres

Requête API sont des paires clé-valeur ajoutées à l'URL d'une requête API pour envoyer des informations supplémentaires au serveur. Ils permettent aux clients (tels que les navigateurs Web ou les applications) de spécifier certains critères ou de transmettre des données lors d'une requête au serveur.

Les paramètres de requête sont ajoutés à la fin de l'URL après un point d'interrogation (?). Chaque paramètre est une paire clé-valeur, la clé et la valeur étant séparées par un signe égal (=). S'il existe plusieurs paramètres de requête, ils sont séparés par une esperluette (&).

Comment les paramètres de requête sont utilisés :
Filtrage des données : les clients peuvent utiliser des paramètres de requête pour filtrer les données de leur choix. Par exemple, ?category=books peut indiquer au serveur de renvoyer uniquement les éléments de la catégorie « livres ».

Pagination : les paramètres de requête sont souvent utilisés pour la pagination dans les requêtes API, permettant au client de spécifier quelle page de résultats récupérer et combien d'éléments par page. Exemple : ?page=2&limit=10.

Tri et classement : les paramètres de requête peuvent être utilisés pour spécifier comment les données doivent être triées. Par exemple, ?sort=price&order=asc pourrait demander au serveur de renvoyer les articles triés par prix par ordre croissant.

Transmission des termes de recherche : les API utilisent souvent des paramètres de requête pour permettre aux clients de rechercher des données. Par exemple, ?search=laptop peut être utilisé pour rechercher tous les produits correspondant au terme « ordinateur portable ».

Les paramètres de requête sont très flexibles et peuvent être utilisés de différentes manières, en fonction de la conception de l'API. Ils permettent une interaction dynamique entre le client et le serveur, facilitant ainsi la demande de données personnalisées.

1. Gestion des paramètres de requête de base Ce gestionnaire d'API montre comment extraire et utiliser les paramètres de requête pour renvoyer un message d'accueil personnalisé.

// pages/api/greet.js

export default function handler(req, res) {
  const { name } = req.query; // Get the 'name' query parameter
  const greeting = name ? `Hello, ${name}!` : 'Hello, stranger!';

  res.status(200).json({ message: greeting });
}

Exemple d'utilisation :
/api/greet?name=John renverra { "message": "Bonjour John!" }
/api/greet renverra { "message": "Bonjour, étranger !" }

1. Paramètres de requête multiples Dans cet exemple, le gestionnaire d'API extrait plusieurs paramètres de requête pour renvoyer une réponse formatée basée sur les entrées de l'utilisateur.

// pages/api/user.js

export default function handler(req, res) {
  const { name, age } = req.query; // Get 'name' and 'age' query parameters

  if (!name || !age) {
    res.status(400).json({ error: 'Name and age are required' });
    return;
  }

  res.status(200).json({ message: `User ${name} is ${age} years old.` });
}

Exemple d'utilisation :
/api/user?name=Jane&age=28 renverra { "message": "L'utilisateur Jane a 28 ans." }
/api/user?name=Jane renverra { "error": "Le nom et l'âge sont requis" }

1. Paramètres de requête facultatifs avec valeurs par défaut Cet exemple montre comment gérer les paramètres de requête facultatifs en fournissant des valeurs par défaut lorsque des paramètres sont manquants.

// pages/api/score.js

export default function handler(req, res) {
  const { player = 'Anonymous', score = '0' } = req.query; // Default values if missing

  res.status(200).json({ message: `${player} scored ${score} points!` });
}

Exemple d'utilisation :
/api/score?player=Alex&score=100 renverra { "message": "Alex a marqué 100 points !" }
/api/score renverra { "message": "Anonyme a marqué 0 point !" }

1. Gestion des tableaux dans les paramètres de requête Next.js permet de transmettre les paramètres de requête sous forme de tableaux. Cet exemple montre comment gérer un tableau de valeurs.

// pages/api/tags.js

export default function handler(req, res) {
  const { tags } = req.query; // Get 'tags' query parameter (array)

  if (!tags) {
    res.status(400).json({ error: 'Tags are required' });
    return;
  }

  res.status(200).json({ message: `You have selected these tags: ${tags.join(', ')}` });
}

Exemple d'utilisation :
/api/tags?tags=javascript&tags=react renverra { "message": "Vous avez sélectionné ces balises : javascript, réagir" }
/api/tags renverra { "error": "Les balises sont requises" }

1. Pagination avec paramètres de requête Ce gestionnaire montre comment implémenter la pagination à l'aide des paramètres de requête pour la page et la limite.

// pages/api/items.js

export default function handler(req, res) {
  const { page = 1, limit = 10 } = req.query; // Default values for page and limit
  const startIndex = (page - 1) * limit;
  const endIndex = startIndex   Number(limit);

  // Dummy data for demonstration
  const items = Array.from({ length: 100 }, (_, i) => `Item ${i   1}`);
  const paginatedItems = items.slice(startIndex, endIndex);

  res.status(200).json({
    currentPage: page,
    perPage: limit,
    items: paginatedItems,
  });
}

Exemple d'utilisation :
/api/items?page=2&limit=5 renverra les 5 éléments suivants, tels que { "items": ["Item 6", "Item 7", "Item 8", "Item 9", "Item 10"] }
/api/items (valeurs par défaut) renverra les 10 premiers éléments, tels que { "items": ["Item 1", "Item 2", ..., "Item 10"] }

Ces exemples démontrent la flexibilité de l'utilisation des paramètres de requête dans les routes de l'API Next.js, couvrant des modèles courants tels que des paramètres uniques ou multiples, des valeurs facultatives, des tableaux et la pagination.