Los parámetros de consulta de API son ​​pares clave-valor que se agregan a la URL de una solicitud de API para enviar información adicional al servidor. Permiten a los clientes (como navegadores web o aplicaciones) especificar ciertos criterios o pasar datos al realizar una solicitud al servidor.

Los parámetros de consulta se agregan al final de la URL después de un signo de interrogación (?). Cada parámetro es un par clave-valor, con la clave y el valor separados por un signo igual (=). Si hay varios parámetros de consulta, están separados por un signo comercial (&).

Cómo se utilizan los parámetros de consulta:
Filtrado de datos: los clientes pueden utilizar parámetros de consulta para filtrar los datos que desean. Por ejemplo, ?category=books podría indicarle al servidor que solo devuelva artículos de la categoría "libros".

Paginación: los parámetros de consulta se utilizan a menudo para la paginación en solicitudes de API, lo que permite al cliente especificar qué página de resultados buscar y cuántos elementos por página. Ejemplo: ?página=2&límite=10.

Clasificación y ordenamiento: los parámetros de consulta se pueden utilizar para especificar cómo se deben ordenar los datos. Por ejemplo, ?sort=price&order=asc podría indicarle al servidor que devuelva artículos ordenados por precio en orden ascendente.

Pasar términos de búsqueda: las API suelen utilizar parámetros de consulta para permitir a los clientes buscar datos. Por ejemplo, ?search=laptop podría usarse para buscar todos los productos que coincidan con el término "laptop".

Los parámetros de consulta son muy flexibles y se pueden utilizar de varias maneras, dependiendo de cómo esté diseñada la API. Permiten una interacción dinámica entre el cliente y el servidor, facilitando la solicitud de datos personalizados.

1. Manejo básico de parámetros de consulta Este controlador de API demuestra cómo extraer y utilizar parámetros de consulta para devolver un saludo personalizado.

// 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 });
}

Ejemplo de uso:
/api/greet?name=John devolverá { "mensaje": "¡Hola, John!" }
/api/greet devolverá { "mensaje": "¡Hola, extraño!" }

1. Múltiples parámetros de consulta En este ejemplo, el controlador de API extrae varios parámetros de consulta para devolver una respuesta formateada según las entradas del usuario.

// 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.` });
}

Ejemplo de uso:
/api/user?name=Jane&age=28 devolverá { "mensaje": "La usuaria Jane tiene 28 años". }
/api/user?name=Jane devolverá { "error": "El nombre y la edad son obligatorios" }

1. Parámetros de consulta opcionales con valores predeterminados Este ejemplo muestra cómo manejar parámetros de consulta opcionales proporcionando valores predeterminados cuando faltan parámetros.

// 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!` });
}

Ejemplo de uso:
/api/score?player=Alex&score=100 devolverá { "message": "¡Alex anotó 100 puntos!" }
/api/score devolverá { "mensaje": "¡Anónimo obtuvo 0 puntos!" }

1. Manejo de matrices en parámetros de consulta Next.js permite pasar parámetros de consulta como matrices. Este ejemplo demuestra cómo manejar una matriz de valores.

// 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(', ')}` });
}

Ejemplo de uso:
/api/tags?tags=javascript&tags=react devolverá { "message": "Has seleccionado estas etiquetas: javascript, reaccionar" }
/api/tags devolverá { "error": "Se requieren etiquetas" }

1. Paginación con parámetros de consulta Este controlador demuestra cómo implementar la paginación utilizando parámetros de consulta para página y límite.

// 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,
  });
}

Ejemplo de uso:
/api/items?page=2&limit=5 devolverá los siguientes 5 elementos, como { "items": ["Elemento 6", "Elemento 7", "Elemento 8", "Elemento 9", "Elemento 10"] }
/api/items (valores predeterminados) devolverá los primeros 10 elementos, como { "items": ["Elemento 1", "Elemento 2", ..., "Elemento 10"] }

Estos ejemplos demuestran la flexibilidad de usar parámetros de consulta en rutas API de Next.js, cubriendo patrones comunes como parámetros únicos o múltiples, valores opcionales, matrices y paginación.