Enviando códigos de status HTTP - FastAPI

O envio de códigos de status HTTP é uma tarefa essencial em aplicações web, pois esses códigos fornecem informações sobre o resultado das operações realizadas no servidor.

Códigos de Status HTTP

Os códigos de status HTTP são categorizados em grupos, cada um indicando um tipo específico de resposta:

• 1xx (Informativos): Indicam que a solicitação foi recebida e está sendo processada. Essas respostas não incluem conteúdo.

• 2xx (Sucesso): Indicam que a operação foi bem-sucedida.

• 3xx (Redirecionamentos): Indicam que o cliente deve tomar ações adicionais para concluir a solicitação (ex.: redirecionamentos).

• 4xx (Erros do Cliente): Indicam problemas causados por solicitações inválidas feitas pelo cliente.

• 5xx (Erros do Servidor): Indicam falhas internas do servidor ao processar a solicitação.

No FastAPI, o código de status padrão retornado é 200 (OK), mas você pode configurar qualquer código necessário para sua aplicação.

Configurando Códigos de Status com o Parâmetro status_code

O parâmetro status_code permite definir o código de status HTTP diretamente em manipuladores de rota. Ele é suportado por métodos como get(), post(), put(), entre outros.

Veja um exemplo:

from fastapi import FastAPI
 
app = FastAPI()
    
@app.get("/notfound", status_code=404)
def notfound():
    return {"message": "Resource Not Found"}

Nesse exemplo, ao acessar o endpoint /notfound, o cliente recebe uma resposta com o código 404, indicando que o recurso solicitado não foi encontrado.

Uso de Constantes do Módulo status

Para melhorar a legibilidade e a manutenção do código, o FastAPI fornece o módulo status, que contém constantes predefinidas representando os códigos de status HTTP. Isso elimina a necessidade de lembrar os números específicos.

Exemplos de constantes:

• HTTP_200_OK (código 200)

• HTTP_404_NOT_FOUND (código 404)

• HTTP_500_INTERNAL_SERVER_ERROR (código 500)

Exemplo utilizando o módulo status:

from fastapi import FastAPI, status
 
app = FastAPI()
    
@app.get("/notfound", status_code=status.HTTP_404_NOT_FOUND)
def notfound():
    return {"message": "Resource Not Found"}

Configurando Códigos de Status de Forma Dinâmica

Em muitos casos, o código de status depende de condições específicas durante o processamento da solicitação. Para isso, você pode utilizar o parâmetro status_code da classe Response (ou subclasses como JSONResponse).

Veja um exemplo:

from fastapi import FastAPI
from fastapi.responses import JSONResponse
    
app = FastAPI()
    
@app.get("/users/{id}")
def get_user(id: int):
    if id < 1:
        return JSONResponse(content={"error": "Invalid ID"}, status_code=400)
    return JSONResponse(content={"message": f"User ID {id} found"}, status_code=200)

Nesse exemplo, o código de status é definido com base no valor do parâmetro id. Se o valor for menor que 1, a resposta terá o código 400 (Bad Request); caso contrário, o código será 200 (OK).

Combinando Abordagens

Em cenários mais complexos, é possível combinar a configuração inicial do código de status com modificações dinâmicas baseadas em lógica condicional:

from fastapi import FastAPI, Response, Path
 
app = FastAPI()
    
@app.get("/users/{id}", status_code=200)
def users(response: Response, id: int = Path()):
    if id < 1:
        response.status_code = 400  # Bad Request
        return {"message": "Incorrect Data"}
    return {"message": f"Id = {id}"}

Nesse exemplo, o código de status padrão é 200 (OK), mas é alterado para 400 (Bad Request) se o valor de id for menor que 1.