Header Parameters
You can define Header parameters the same way you define Query
, Path
and Cookie
parameters.
Import Header
First import Header
:
from typing import Optional
from flask_sugar import Sugar, Header
app = Sugar(__name__)
@app.get("/")
def index(user_agent: Optional[str] = Header(None)):
return {"user_agent": user_agent}
Declare Header
parameters
Then declare the header parameters using the same structure as with Path
, Query
and Cookie
.
The first value is the default value, you can pass all the extra validation or annotation parameters:
from typing import Optional
from flask_sugar import Sugar, Header
app = Sugar(__name__)
@app.get("/")
def index(user_agent: Optional[str] = Header(None)):
return {"user_agent": user_agent}
Technical Details
Header
is a "sister" class of Path
, Query
and Cookie
. It also inherits from the same common Param
class.
But remember that when you import Query
, Path
, Header
, and others from flask_sugar
, those are actually functions that return special classes.
Info
To declare headers, you need to use Header
, because otherwise the parameters would be interpreted as query parameters.
Automatic conversion
Header
has a little extra functionality on top of what Path
, Query
and Cookie
provide.
Most of the standard headers are separated by a "hyphen" character, also known as the "minus symbol" (-
).
But a variable like user-agent
is invalid in Python.
So, by default, Header
will convert the parameter names characters from underscore (_
) to hyphen (-
) to extract and document the headers.
Also, HTTP headers are case-insensitive, so, you can declare them with standard Python style (also known as "snake_case").
So, you can use user_agent
as you normally would in Python code, instead of needing to capitalize the first letters as User_Agent
or something similar.
List headers
It is possible to receive a header with multiple values.
You can define those cases using a list in the type declaration.
You will split the value in the header into a Python list
.
For example, to declare a header values with multiple values, you can write:
from flask_sugar import Sugar, Header
app = Sugar(__name__)
@app.get("/")
def index(x_token: List[str] = Header(None)):
return {"X-Token values": x_token}
If you communicate with that path operation sending a HTTP headers like:
X-Token: foo,bar
The response would be like:
{
"X-Token values": [
"bar",
"foo"
]
}
Recap
Declare headers with Header
, using the same common pattern as Query
, Path
and Cookie
.
And don't worry about underscores in your variables, FLask Sugar will take care of converting them.