Parámetros de Consulta em FastAPI

Os parâmetros de consulta (query string) são usados para passar informações para a API através da URL, por meio da URL em requisições do tipo GET. Antes de explorar seu funcionamento, é importante compreender o conceito de consulta. Considere o seguinte exemplo de URL:

http://127.0.0.1:8000/users/add?name=Tom&age=38

Neste caso:

• A parte que aparece após o endereço do servidor e a porta, mas antes do caractere ? — ou seja, users/add — representa o caminho da rota (path).
• A parte que aparece após o ?, ou seja, name=Tom&age=38, é a query string ou parâmetros de consulta.

Os parâmetros de consulta consistem em pares de chave e valor, separados pelo símbolo =. Por exemplo:

• O parâmetro name tem o valor "Tom".
• O parâmetro age tem o valor 38.

Se houver múltiplos parâmetros, eles são separados pelo caractere ampersand &, como no exemplo acima.

Obtendo Valores dos Parâmetros de Consulta

Para acessar os valores de parâmetros de consulta em uma aplicação FastAPI, basta defini-los como argumentos da função associada à rota:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
def get_model(name, age):
    return {"user_name": name, "user_age": age}

Neste caso, ao receber uma requisição como /users?name=Tom&age=38, a aplicação captura os valores dos parâmetros name e age e os retorna como um dicionário JSON.

Valores Padrão para Parâmetros de Consulta

Em alguns casos, os usuários podem não fornecer todos os parâmetros esperados. No exemplo anterior, ambos os parâmetros são obrigatórios, e a ausência de qualquer um deles resultaria em um erro. Para evitar isso, é possível atribuir valores padrão aos parâmetros:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
def get_model(name="Undefined", age=18):
    return {"user_name": name, "user_age": age}

Com essa configuração:

• Se o parâmetro name não for fornecido, o valor "Undefined" será utilizado.
• Se o parâmetro age não for fornecido, o valor padrão será 18.

Por exemplo, a requisição /users?name=Tom resultaria em:

{"user_name": "Tom", "user_age": 18}

Parâmetros com valores padrão devem ser declarados após parâmetros obrigatórios, para evitar conflitos de ordem.

Restrições de Tipo nos Parâmetros de Consulta

O FastAPI também permite aplicar restrições de tipo aos parâmetros, garantindo que os valores fornecidos atendam aos requisitos esperados:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
def get_model(name: str, age: int = 18):
    return {"user_name": name, "user_age": age}

Aqui:

• O parâmetro name deve ser uma string (str).
• O parâmetro age deve ser um número inteiro (int) e, se não for fornecido, será atribuído o valor padrão 18.

Se o tipo de dado enviado não for compatível — por exemplo, um valor não numérico para age — o FastAPI retornará um erro de validação automaticamente.

Parâmetros de Consulta com a Classe Query

O FastAPI oferece a classe Query, fornecida pelo pacote fastapi, para lidar de forma mais avançada com os parâmetros de consulta. Essa classe possibilita a validação detalhada dos valores recebidos e fornece uma ampla gama de configurações para garantir que os dados atendam aos requisitos esperados.

Validações com a Classe Query

A classe Query permite definir diversas validações para os valores dos parâmetros. Aqui estão os principais argumentos que podem ser usados:

• min_length: Define o número mínimo de caracteres permitidos para o valor.
• max_length: Define o número máximo de caracteres permitidos para o valor.
• pattern: Aplica uma validação baseada em uma expressão regular.
• lt: Garante que o valor seja menor que um número definido.
• le: Garante que o valor seja menor ou igual a um número definido.
• gt: Garante que o valor seja maior que um número definido.
• ge: Garante que o valor seja maior ou igual a um número definido.

Exemplo Básico de Validação

No exemplo a seguir, validamos o parâmetro name para garantir que ele tenha entre 3 e 20 caracteres:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
def users(name: str = Query(min_length=3, max_length=20)):
    return {"name": name}

Aqui, o parâmetro name será validado com as seguintes regras:

• Deve conter pelo menos 3 caracteres.
• Não pode ultrapassar 20 caracteres.

Múltiplas Validações

Com a classe Query, é possível aplicar múltiplas validações em diferentes parâmetros. Por exemplo:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
def users(
    name: str = Query(min_length=3, max_length=20),
    age: int = Query(ge=18, lt=111)
):
    return {"name": name, "age": age}

Neste caso:

• O parâmetro name deve ter entre 3 e 20 caracteres.
• O parâmetro age deve ser um número entre 18 (inclusive) e 111 (exclusivo).

Validação com Expressões Regulares

O argumento pattern pode ser usado para validar valores com base em expressões regulares. No exemplo abaixo, o parâmetro phone deve conter exatamente 11 dígitos:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
def users(phone: str = Query(pattern=r"^\d{11}$")):
    return {"phone": phone}

Se o valor enviado não corresponder ao padrão definido pela expressão regular, um erro de validação será retornado automaticamente.

Definindo Valores Padrão

Também é possível definir valores padrão para parâmetros usando o argumento default:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
def users(name: str = Query(default="Undefined", min_length=2)):
    return {"name": name}

Se o parâmetro name não for incluído na query string, o valor padrão "Undefined" será usado.

Parâmetros opcionais

Para tornar um parâmetro opcional, basta definir seu valor padrão como None:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
def users(name: str | None = Query(default=None, min_length=2)):
    if name is None:
        return {"name": "Undefined"}
    else:
        return {"name": name}

Aqui, se o parâmetro name não for fornecido, a aplicação responderá com "Undefined".

Recebendo Listas de Valores

A classe Query também suporta parâmetros que representam listas de valores. Por exemplo, no caso de uma query string contendo múltiplos valores para o mesmo parâmetro:

http://127.0.0.1:8000/users?people=Tom&people=Sam&people=Bob

O código abaixo ilustra como capturar esses valores como uma lista:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
def users(people: list[str] = Query()):
    return {"people": people}

Neste caso, o parâmetro people será convertido em uma lista contendo os valores ["tom", "Sam", "Bob"].

Combinando Parâmetros de Rota e Consulta

Por fim, é possível combinar parâmetros de rota com parâmetros de consulta em uma mesma rota. Veja o exemplo:

from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/users/{name}")
def users(
    name: str = Path(min_length=3, max_length=20),
    age: int = Query(ge=18, lt=111)
):
    return {"name": name, "age": age}

Aqui:

• O parâmetro name é um parâmetro de rota, cuja validação exige entre 3 e 20 caracteres.
• O parâmetro age é um parâmetro de consulta, que deve ser um número entre 18 (inclusive) e 111 (exclusivo).

Por exemplo, a requisição para o endereço:

http://127.0.0.1:8000/users/Tom?age=38

Resultará na resposta:

{
  "name": "Tom",
  "age": 38
}

Documentação oficial:

• Parâmetros de Consulta (Query Parameters) - FastAPI
• Parâmetros de Rota (Path Parameters) - FastAPI