Parâmetros de Rota - FastAPI

Os parâmetros de rota permitem que valores específicos sejam passados diretamente no caminho da URL. No FastAPI, esses valores são vinculados automaticamente aos argumentos da função que processa a requisição. Esses parâmetros, também conhecidos como path parameters, são úteis para configurar endpoints dinâmicos e transferir informações diretamente pela URL.

Definição de Parâmetros de Rota

Parâmetros de rota são declarados diretamente na rota, delimitados por chaves {}. Veja o exemplo abaixo:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{id}")
def get_user(id: int):
    return {"user_id": id}

Nesse caso, o decorador app.get utiliza a rota "/users/{id}". O {id} define o parâmetro de rota id.

A função get_user(), que processa as requisições enviadas para essa rota, recebe o parâmetro id. O valor correspondente ao segmento da URL será passado automaticamente para a função, conforme interpretado pelo FastAPI.

Considere uma requisição para o endereço http://127.0.0.1:8000/users/315. O caminho da requisição é users/315. O FastAPI reconhece que esse caminho corresponde à rota "/users/{id}" e, portanto, a função get_user() será chamada.

O parâmetro id na rota corresponde ao segundo segmento do caminho. Assim, o framework associa o valor "315" ao parâmetro id. Ao acessar a URL http://127.0.0.1:8000/users/315, a função get_user() receberá id=315.

O FastAPI também suporta a definição de múltiplos parâmetros de rota. Veja o exemplo abaixo:

from fastapi import FastAPI

app = FastAPI()

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

Nesse caso, a função get_user() processará requisições que correspondam à rota "/users/{name}/{age}". Essa rota espera um caminho com três segmentos: o primeiro é users, o segundo representa o parâmetro name, e o terceiro, o parâmetro age.

Por exemplo, uma requisição para http://127.0.0.1:8000/users/Tom/38 resultará em:

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

Embora o separador padrão entre os segmentos de uma rota seja a barra (/), é possível utilizar outros caracteres, como o hífen (-). Veja o exemplo:

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

Nesse caso, uma requisição para http://127.0.0.1:8000/users/Joao-25 será interpretada corretamente pelo FastAPI. O framework identificará os valores do parâmetro name como "Joao" e do parâmetro age como "25".

Ordem de Definição das Rotas

Ao definir rotas, é importante considerar que podem surgir ambiguidades entre elas, quando uma requisição corresponde a mais de uma rota definida. Por isso, a ordem em que as rotas são declaradas no código deve ser cuidadosamente planejada. Veja o exemplo abaixo:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{name}")
def get_user(name):
    return {"user_name": name}

@app.get("/users/admin")
def get_admin():
    return {"message": "Hello admin"}

Nesse caso, queremos que as requisições para a rota "/users/admin" sejam processadas pela função get_admin(). Já as requisições que seguem o padrão "/users/{name}", onde o segundo segmento representa o parâmetro name, devem ser processadas pela função get_user().

No entanto, ao acessar o endereço http://127.0.0.1:8000/users/admin, vemos que a requisição é tratada pela função get_user(), e não pela get_admin().

Isso ocorre porque a função get_user foi definida antes da função get_admin. Portanto, a rota "/users/{name}" é avaliada primeiro, e qualquer requisição que corresponda a esse padrão será tratada por ela.

Para resolver esse problema, basta trocar a ordem das definições das funções:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/admin")
def get_admin():
    return {"message": "Hello admin"}

@app.get("/users/{name}")
def get_user(name):
    return {"user_name": name}

Restrições de Tipo para Parâmetros

O FastAPI permite definir restrições de tipo para os parâmetros de rota. Isso é feito especificando o tipo esperado diretamente na declaração do parâmetro. Por exemplo, podemos configurar o parâmetro id para aceitar apenas números inteiros:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{id: int}")
def get_user(id: int):
    return {"user_id": id}

Ao declarar explicitamente o tipo int para o parâmetro id, garantimos que ele só aceitará valores inteiros. Se uma requisição enviar um valor não numérico para esse parâmetro, o servidor retornará automaticamente uma mensagem de erro indicando o problema.

Além de int, o FastAPI permite especificar outros tipos de daddos, como str, float, bool, entre outros.

Validação de Parâmetros com a classe Path

O FastAPI fornece a classe Path do módulo fastapi para facilitar a validação de parâmetros de rota. Com a classe Path, é possível aplicar diversas validações aos valores recebidos. Entre os parâmetros disponíveis no construtor de Path, destacam-se:

• min_length: define o número mínimo de caracteres que o valor deve ter.

• max_length: define o número máximo de caracteres que o valor pode ter.

• pattern: aplica uma expressão regular ao valor, que deve ser correspondida.

• lt: o valor deve ser menor que o especificado.

• le: o valor deve ser menor ou igual ao especificado.

• gt: o valor deve ser maior que o especificado.

• ge: o valor deve ser maior ou igual ao especificado.

Veja um exemplo de uso da classe Path para validar o número de caracteres de um parâmetro de rota:

from fastapi import FastAPI, Path

app = FastAPI()

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

Neste exemplo, o parâmetro name é recebido na rota. O valor desse parâmetro deve ter pelo menos 3 caracteres e no máximo 20 caracteres.

Da mesma forma, podemos aplicar validações numéricas a parâmetros inteiros. Por exemplo, podemos definir que o parâmetro age deve ser maior ou igual a 18 e menor que 111:

from fastapi import FastAPI, Path

app = FastAPI()

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

Além disso, podemos aplicar expressões regulares para validar o formato de um parâmetro. Por exemplo, podemos definir que o parâmetro phone deve conter exatamente 11 dígitos:

from fastapi import FastAPI, Path

app = FastAPI()

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