Nexios

Appearance

Headers ​

Access incoming request headers through the request.headers property, which provides a case-insensitive dictionary-like interface:

python
from nexios import NexiosApp
app = NexiosApp()
@app.get("/")
async def show_headers(request, response):
    user_agent = request.headers.get("user-agent")
    accept_language = request.headers.get("accept-language")
    return {
        "user_agent": user_agent,
        "accept_language": accept_language
    }

Common Request Headers ​

HeaderDescriptionExample
AcceptContent types the client can processapplication/json, text/html
AuthorizationCredentials for authenticationBearer xyz123
Content-TypeMedia type of the request bodyapplication/json
CookieCookies sent by the clientsession_id=abc123
User-AgentClient application informationMozilla/5.0
X-Requested-WithIndicates AJAX requestXMLHttpRequest

Tip

Nexios normalizes header names to lowercase, so request.headers.get("User-Agent") and request.headers.get("user-agent") are equivalent.

Response Headers ​

Set response headers using the response.set_header() method or by passing a headers dictionary:

python
from nexios import NexiosApp
app = NexiosApp()
@app.get("/")
async def set_headers(request, response):
    response.set_header("X-Custom-Header", "Custom Value")
    response.set_header("Cache-Control", "no-store")
    return response.text("Hello, World!")

Common Response Headers ​

HeaderDescriptionExample
Content-TypeMedia type of the responsetext/html; charset=utf-8
Cache-ControlCaching directivesmax-age=3600
Set-CookieSets cookies on clientsession_id=abc123; Path=/
LocationURL for redirectshttps://example.com/new
X-Frame-OptionsClickjacking protectionDENY
Content-Security-PolicySecurity policydefault-src 'self'

Setting Headers In Middleware ​

In middleware, you need to modify headers after the response has been created by the route handler.

Correct Middleware Pattern ​

Always set headers after calling await call_next():

python
async def cors_middleware(request, response, call_next):
    response = await call_next()
    response.set_header("Access-Control-Allow-Origin", "*")
    response.set_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
    response.set_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
    return response

Common Middleware Use Cases ​

CORS Headers ​

python
async def cors_middleware(request, response, call_next):
    response = await call_next()
    response.set_header("Access-Control-Allow-Origin", "*")
    response.set_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
    response.set_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
    response.set_header("Access-Control-Max-Age", "86400")
    return response

Security Headers ​

python
async def security_middleware(request, response, call_next):
    response = await call_next()
    response.set_header("X-Content-Type-Options", "nosniff")
    response.set_header("X-Frame-Options", "DENY")
    response.set_header("X-XSS-Protection", "1; mode=block")
    response.set_header("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
    return response

Request ID Tracking ​

python
async def request_id_middleware(request, response, call_next):
    request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
    response = await call_next()
    response.set_header("X-Request-ID", request_id)
    return response

Best Practice

In route handlers, prefer passing headers as arguments to response methods for cleaner code:

python
# Clean approach for handlers
@app.get("/api/data")
async def get_data(req, res):
    return res.json(
        {"data": "success"}, 
        headers={
            "X-API-Version": "1.0",
            "Cache-Control": "no-cache"
        }
    )

Use set_header() primarily in middleware where you need to modify responses after they're created.

Header Manipulation Methods ​

Nexios provides several methods for working with headers:

Request Header Methods ​

  • request.headers.get(key, default=None) - Get a header value
  • request.headers.items() - Get all headers as key-value pairs
  • request.headers.keys() - Get all header names
  • request.headers.values() - Get all header values

Response Header Methods ​

  • response.set_header(key, value, override=False) - Set a header
  • response.remove_header(key) - Remove a header
  • response.has_header(key) - Check if header exists
  • response.set_headers(headers_dict, override_all=False) - Set multiple headers

Security Headers Best Practices ​

For enhanced security, consider these recommended headers:

python
@app.middleware
async def add_security_headers(request, response, next):
    response.set_headers({
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "X-XSS-Protection": "1; mode=block",
        "Referrer-Policy": "strict-origin-when-cross-origin",
        "Content-Security-Policy": "default-src 'self'; script-src 'self'",
        "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload"
    })
    await next()

Performance Headers ​

Optimize client-side caching and resource loading:

python
@app.middleware
async def add_performance_headers(request, response, next):
    if request.path.endswith(('.js', '.css', '.png', '.jpg')):
        response.set_header("Cache-Control", "public, max-age=31536000, immutable")
    await next()

Cookies are set via special Set-Cookie headers:

python
@app.get("/login")
async def login(request, response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        max_age=3600,
        secure=True,
        httponly=True,
        samesite="strict"
    )
    return response.redirect("/dashboard")

Conditional Headers ​

Handle conditional requests with these headers:

HeaderPurposeExample
If-Modified-SinceCheck if resource changedSat, 01 Jan 2022 00:00:00 GMT
If-None-MatchCheck ETag match"abc123"
ETagResource version identifierW/"xyz456"
Last-ModifiedResource modification timeSat, 01 Jan 2022 00:00:00 GMT

Restricted Headers ​

Some headers are restricted and cannot be modified:

  • Content-Length (automatically calculated)
  • Connection
  • Transfer-Encoding
  • Host

⚠️ Warning

Always set headers after the request is processed in middleware when modifying responses. Setting headers too early may result in them being overwritten.

Further Reading ​