Os parâmetros

consulta de API são pares de valores-chave anexados ao URL de uma solicitação de API para enviar informações adicionais ao servidor. Eles permitem que clientes (como navegadores da web ou aplicativos) especifiquem determinados critérios ou passem dados ao fazer uma solicitação ao servidor.

Os parâmetros de consulta são adicionados ao final da URL após um ponto de interrogação (?). Cada parâmetro é um par chave-valor, com a chave e o valor separados por um sinal de igual (=). Se houver vários parâmetros de consulta, eles serão separados por um E comercial (&).

Como os parâmetros de consulta são usados:
Filtragem de dados: os clientes podem usar parâmetros de consulta para filtrar os dados que desejam. Por exemplo, ?category=books pode informar ao servidor para retornar apenas itens da categoria "livros".

Paginação: parâmetros de consulta são frequentemente usados ​​para paginação em solicitações de API, permitindo que o cliente especifique qual página de resultados buscar e quantos itens por página. Exemplo: ?page=2&limit=10.

Classificação e ordenação: parâmetros de consulta podem ser usados ​​para especificar como os dados devem ser classificados. Por exemplo, ?sort=price&order=asc poderia instruir o servidor a retornar itens classificados por preço em ordem crescente.

Passando termos de pesquisa: APIs geralmente usam parâmetros de consulta para permitir que os clientes pesquisem dados. Por exemplo, ?search=laptop pode ser usado para encontrar todos os produtos que correspondem ao termo "laptop".

Os parâmetros de consulta são altamente flexíveis e podem ser usados ​​de diversas maneiras, dependendo de como a API foi projetada. Eles permitem a interação dinâmica entre cliente e servidor, facilitando a solicitação de dados customizados.

1. Tratamento básico de parâmetros de consulta Este manipulador de API demonstra como extrair e usar parâmetros de consulta para retornar uma saudação personalizada.

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

Exemplo de uso:
/api/greet?name=John retornará { "message": "Olá, John!" }
/api/greet retornará { "message": "Olá, estranho!" }

1. Vários parâmetros de consulta Neste exemplo, o manipulador de API extrai vários parâmetros de consulta para retornar uma resposta formatada com base nas entradas do usuário.

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

Exemplo de uso:
/api/user?name=Jane&age=28 retornará { "message": "A usuária Jane tem 28 anos." }
/api/user?name=Jane retornará { "error": "Nome e idade são obrigatórios" }

1. Parâmetros de consulta opcionais com valores padrão Este exemplo mostra como lidar com parâmetros de consulta opcionais, fornecendo valores padrão quando os parâmetros estão faltando.

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

Exemplo de uso:
/api/score?player=Alex&score=100 retornará { "message": "Alex marcou 100 pontos!" }
/api/score retornará { "message": "Anonymous marcou 0 pontos!" }

1. Tratamento de matrizes em parâmetros de consulta Next.js permite que parâmetros de consulta sejam passados ​​como arrays. Este exemplo demonstra como lidar com uma 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(', ')}` });
}

Exemplo de uso:
/api/tags?tags=javascript&tags=react retornará { "message": "Você selecionou estas tags: javascript, react" }
/api/tags retornará { "error": "Tags são obrigatórias" }

1. Paginação com parâmetros de consulta Este manipulador demonstra como implementar a paginação usando parâmetros de consulta para página e 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,
  });
}

Exemplo de uso:
/api/items?page=2&limit=5 retornará os próximos 5 itens, como { "items": ["Item 6", "Item 7", "Item 8", "Item 9", "Item 10"] }
/api/items (valores padrão) retornará os primeiros 10 itens, como { "items": ["Item 1", "Item 2", ..., "Item 10"] }

Esses exemplos demonstram a flexibilidade do uso de parâmetros de consulta em rotas da API Next.js, cobrindo padrões comuns como parâmetros únicos ou múltiplos, valores opcionais, matrizes e paginação.