Headers¶

Setting up headers is also something that usually happens within the scope of almost any application.

Let's assume you need to setup a header in your application. There are a few ways.

In your API you need a header to be passed onto the call to make you run some extra security validations.

from pydantic import BaseModel, EmailStr

from esmerald import Esmerald, Gateway, Header, JSONResponse, post


class User(BaseModel):
    name: str
    email: EmailStr


@post(path="/create")
async def create_user(
    data: User,
    token: str = Header(value="X-API-TOKEN"),
) -> JSONResponse:
    """
    Run validations with the token header
    """
    ...


app = Esmerald(routes=Gateway(handler=create_user))

The header is nothing more nothing less than pydantic FieldInfo with some extra things specific for the header that extends the Param.

from esmerald import Param

# or

from esmerald.params import Param

The same result can be achieved by using directly the Param field.

from pydantic import BaseModel, EmailStr

from esmerald import Esmerald, Gateway, JSONResponse, Param, post


class User(BaseModel):
    name: str
    email: EmailStr


@post(path="/create")
async def create_user(
    data: User,
    token: str = Param(header="X-API-TOKEN"),
) -> JSONResponse:
    """
    Run validations with the token header
    """
    ...


app = Esmerald(routes=Gateway(handler=create_user))

Since the Param is the base for the Esmerald parameters, you can use it directly with a key difference.

the Header expects a value field whereas the Param expects a header value.

If a header is defined and not sent properly when the call is made it will raise a 400 BadRequest.

Response headers¶

This is something else entirely and it is used when you want to send a header with the response. Very easy to use as well.

The response_headers is a simple python dictionary.

from pydantic import BaseModel, EmailStr

from esmerald import Esmerald, Gateway, Response, post
from esmerald.datastructures import ResponseHeader


class User(BaseModel):
    name: str
    email: EmailStr


@post(path="/create", response_headers={"myauth": ResponseHeader(value="granted")})
async def create_user(data: User) -> Response:
    """
    Run validations with the token header
    """
    ...


app = Esmerald(routes=Gateway(handler=create_user))

When you check the response from the api call, you should now also have a myauth header being sent as well with the value granted.

This is how simple and effective you can manage response headers.

Headers¶

Header¶

Response headers¶