Como usar query params no Express.js?

Os query params no Express.js são utilizados para enviar informações adicionais na URL sem alterar sua estrutura. Eles são úteis para filtragem, ordenação e paginação de dados em APIs.

1. O que são query params?

Query params são passados na URL após um ?, sendo compostos por pares chave=valor.

Exemplo de requisição com query params:

http://localhost:3000/produtos?categoria=eletronicos&preco_max=1000

Aqui, temos dois parâmetros:

categoria = eletronicos
preco_max = 1000

2. Capturando query params no Express.js

Podemos acessar os query params usando req.query:

const express = require('express');
const app = express();

app.get('/produtos', (req, res) => {
    const { categoria, preco_max } = req.query;
    res.json({
        mensagem: 'Filtrando produtos',
        categoria,
        preco_max
    });
});

app.listen(3000, () => {
    console.log('Servidor rodando na porta 3000');
});

Se fizermos uma requisição para http://localhost:3000/produtos?categoria=eletronicos&preco_max=1000, a resposta será:

{
    "mensagem": "Filtrando produtos",
    "categoria": "eletronicos",
    "preco_max": "1000"
}

3. Query params opcionais

Se não passarmos um dos parâmetros na URL, o Express simplesmente os ignorará.

Por exemplo, acessando http://localhost:3000/produtos?categoria=livros, teremos:

{
    "mensagem": "Filtrando produtos",
    "categoria": "livros",
    "preco_max": null
}

4. Convertendo valores de query params

Por padrão, os valores dos query params são strings. Para convertê-los:

const precoMax = Number(req.query.preco_max) || 0;

Conclusão

Os query params são uma forma prática de passar informações adicionais para rotas no Express.js. Eles permitem filtrar, ordenar e personalizar respostas de uma API de maneira dinâmica.

Por que query params são essenciais no desenvolvimento de APIs?

O uso de query params é essencial para APIs modernas. Muitos serviços, como e-commerces e redes sociais, utilizam query params para personalizar resultados. Por exemplo, no Google, os parâmetros de busca são passados via query params, permitindo que o servidor entenda a intenção do usuário sem alterar a estrutura da URL.

Em APIs RESTful, a combinação de query params com paginação e ordenação melhora a eficiência e a experiência do usuário. Isso permite que clientes filtrem dados sem necessidade de múltiplos endpoints fixos.

Algumas aplicações:

Filtragem de produtos em e-commerces
Paginação de resultados em APIs
Ordenação de dados por diferentes critérios
Personalização de buscas em serviços web
Redução do número de endpoints fixos

Dicas para quem está começando

Use req.query para capturar query params.
Verifique se os valores estão no formato correto antes de usá-los.
Query params são opcionais, sempre trate valores ausentes corretamente.
Utilize Number(req.query.valor) para converter strings em números.
Combine query params com parâmetros de URL para APIs mais flexíveis.

Contribuições de Lucas Fernandes

Como usar query params no Express.js?