Custom Responses

from datetime import datetime, timezone
from uuid import UUID

from fastapi import FastAPI
from fastapi.encoders import jsonable_encoder
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()


class Book(BaseModel):
    id: UUID
    title: str
    published_at: datetime
    subtitle: str | None = None


@app.put("/books/{book_id}")
def replace_book(book_id: UUID, book: Book) -> JSONResponse:
    return JSONResponse(content=jsonable_encoder(book), status_code=200)


@app.put("/broken/{book_id}")
def broken(book_id: UUID, book: Book) -> JSONResponse:
    return JSONResponse(content=book.model_dump())  # datetime and UUID are not JSON types


c = TestClient(app, raise_server_exceptions=False)
body = {
    "id": "6f1c1f9e-0d0f-4c0a-9a53-3e6b3b0a1f10",
    "title": "Dune",
    "published_at": "1965-08-01T00:00:00Z",
}
r = c.put("/books/6f1c1f9e-0d0f-4c0a-9a53-3e6b3b0a1f10", json=body)
print(r.status_code, r.headers["content-type"], r.json())
print(c.put("/broken/6f1c1f9e-0d0f-4c0a-9a53-3e6b3b0a1f10", json=body).status_code)
print(jsonable_encoder({"when": datetime(2026, 1, 2, tzinfo=timezone.utc), "n": {1, 2}}))
print(list(c.get("/openapi.json").json()["paths"]["/books/{book_id}"]["put"]["responses"]["200"]))

200 application/json {'id': '6f1c1f9e-0d0f-4c0a-9a53-3e6b3b0a1f10', 'title': 'Dune', 'published_at': '1965-08-01T00:00:00Z', 'subtitle': None}
500
{'when': '2026-01-02T00:00:00+00:00', 'n': [1, 2]}
['description', 'content']

curl -s -X PUT localhost:8000/books/6f1c1f9e-0d0f-4c0a-9a53-3e6b3b0a1f10 \
  -H 'Content-Type: application/json' \
  -d '{"id": "6f1c1f9e-0d0f-4c0a-9a53-3e6b3b0a1f10", "title": "Dune", "published_at": "1965-08-01T00:00:00Z"}'

{"id":"6f1c1f9e-0d0f-4c0a-9a53-3e6b3b0a1f10","title":"Dune","published_at":"1965-08-01T00:00:00Z","subtitle":null}

import csv
import io
import json
from typing import Any

from fastapi import APIRouter, FastAPI, Response
from fastapi.responses import HTMLResponse, JSONResponse
from fastapi.testclient import TestClient


class CSVResponse(Response):
    media_type = "text/csv"

    def render(self, content: Any) -> bytes:
        buffer = io.StringIO()
        writer = csv.writer(buffer)
        for row in content:
            writer.writerow(row)
        return buffer.getvalue().encode("utf-8")


class PrettyJSONResponse(JSONResponse):
    def render(self, content: Any) -> bytes:
        return json.dumps(content, ensure_ascii=False, indent=2).encode("utf-8")


app = FastAPI()


@app.get("/export/books.csv", response_class=CSVResponse)
def export_books() -> list[list[str]]:
    return [["id", "title"], ["1", "Dune"], ["2", "Emma, a novel"]]


@app.get("/debug/books", response_class=PrettyJSONResponse)
def debug_books() -> list[dict]:
    return [{"id": 1, "title": "Dune"}]


c = TestClient(app)
r = c.get("/export/books.csv")
print(r.headers["content-type"]); print(r.text)
print(c.get("/debug/books").text)
print(c.get("/openapi.json").json()["paths"]["/export/books.csv"]["get"]["responses"]["200"]["content"])

# default_response_class
html_app = FastAPI(default_response_class=HTMLResponse)
router = APIRouter(prefix="/api", default_response_class=PrettyJSONResponse)


@html_app.get("/")
def home() -> str:
    return "<h1>Bookshelf</h1>"


@html_app.get("/api-ish", response_class=JSONResponse)
def override() -> dict:
    return {"ok": True}


@router.get("/books")
def books() -> list[dict]:
    return [{"id": 1}]


html_app.include_router(router)
h = TestClient(html_app)
print(h.get("/").headers["content-type"])
print(h.get("/api-ish").headers["content-type"])
print(h.get("/api/books").text.replace("\n", "\\n"))

text/csv; charset=utf-8
id,title
1,Dune
2,"Emma, a novel"

[
  {
    "id": 1,
    "title": "Dune"
  }
]
{'text/csv': {'schema': {'type': 'string'}}}
text/html; charset=utf-8
application/json
[\n  {\n    "id": 1\n  }\n]

from datetime import datetime, timedelta, timezone
from typing import Annotated

from fastapi import FastAPI, Response, Cookie
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()


class BookOut(BaseModel):
    id: int
    title: str


DB = {1: {"id": 1, "title": "Dune", "internal_note": "do not leak"}}


@app.get("/books/{book_id}", response_model=BookOut)
def get_book(book_id: int, response: Response) -> dict:
    response.headers["X-Cache"] = "miss"
    response.headers["Cache-Control"] = "public, max-age=60"
    response.status_code = 200
    return DB[book_id]


@app.get("/direct")
def direct(response: Response) -> JSONResponse:
    response.headers["X-Lost"] = "set on the parameter"
    return JSONResponse({"ok": True}, headers={"X-Kept": "set on the response"})


@app.post("/login")
def login(response: Response) -> dict:
    response.set_cookie(
        key="session_id",
        value="s-42",
        max_age=3600,
        path="/",
        secure=True,
        httponly=True,
        samesite="strict",
    )
    return {"ok": True}


@app.post("/prefs")
def prefs() -> JSONResponse:
    r = JSONResponse({"ok": True})
    r.set_cookie("theme", "dark", expires=datetime.now(timezone.utc) + timedelta(days=30), samesite="lax")
    r.set_cookie("tracking", "x", samesite="none", secure=True)
    return r


@app.post("/logout")
def logout(response: Response, session_id: Annotated[str | None, Cookie()] = None) -> dict:
    response.delete_cookie("session_id", path="/", secure=True, httponly=True, samesite="strict")
    return {"ok": session_id is not None}


c = TestClient(app)
r = c.get("/books/1")
print(r.json(), r.headers["x-cache"], r.headers["cache-control"])
r = c.get("/direct"); print(r.headers.get("x-lost"), r.headers.get("x-kept"))
r = c.post("/login"); print(r.headers.get_list("set-cookie"))
r = c.post("/prefs");
for h in r.headers.get_list("set-cookie"): print(h)
r = c.post("/logout", cookies={"session_id": "s-42"}); print(r.json(), r.headers.get_list("set-cookie"))

{'id': 1, 'title': 'Dune'} miss public, max-age=60
None set on the response
['session_id=s-42; HttpOnly; Max-Age=3600; Path=/; SameSite=strict; Secure']
theme=dark; expires=Sun, 01 Nov 2026 08:39:30 GMT; Path=/; SameSite=lax
tracking=x; Path=/; SameSite=none; Secure
{'ok': True} ['session_id=""; expires=Fri, 02 Oct 2026 08:39:30 GMT; HttpOnly; Max-Age=0; Path=/; SameSite=strict; Secure']

curl -si -X POST localhost:8000/login | grep -i '^set-cookie'

set-cookie: session_id=s-42; HttpOnly; Max-Age=3600; Path=/; SameSite=strict; Secure

import warnings

from fastapi import FastAPI
from fastapi.responses import ORJSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()


class Book(BaseModel):
    id: int
    title: str


@app.get("/old", response_class=ORJSONResponse)
def old() -> list[Book]:
    return [Book(id=1, title="Dune")]


@app.get("/new")
def new() -> list[Book]:
    return [Book(id=1, title="Dune")]


c = TestClient(app)
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    r_old = c.get("/old")
    r_new = c.get("/new")
print([w.category.__name__ for w in caught if "ORJSON" in str(w.message)])
print(r_old.headers["content-type"], r_old.text)
print(r_new.headers["content-type"], r_new.text)

['FastAPIDeprecationWarning']
application/json [{"id":1,"title":"Dune"}]
application/json [{"id":1,"title":"Dune"}]

import struct
import zlib
from io import BytesIO
from typing import Annotated

from fastapi import FastAPI, Query, Response
from fastapi.testclient import TestClient

app = FastAPI()


def make_png(width: int, height: int, rows: list[bytes]) -> bytes:
    """Encode 8-bit grayscale rows as a PNG using only the standard library."""

    def chunk(kind: bytes, data: bytes) -> bytes:
        body = kind + data
        return struct.pack(">I", len(data)) + body + struct.pack(">I", zlib.crc32(body))

    raw = b"".join(b"\x00" + row for row in rows)
    header = struct.pack(">IIBBBBB", width, height, 8, 0, 0, 0, 0)
    return b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", header) + chunk(b"IDAT", zlib.compress(raw)) + chunk(b"IEND", b"")


def rating_chart(ratings: list[int]) -> bytes:
    """A tiny bar chart: one 20-pixel-wide bar per rating (1 to 5)."""
    height = 50
    width = 20 * len(ratings)
    rows = []
    for y in range(height):
        row = bytearray()
        for rating in ratings:
            filled = y >= height - rating * 10
            row += bytes([40 if filled else 230]) * 20
        rows.append(bytes(row))
    return make_png(width, height, rows)


@app.get(
    "/books/{book_id}/ratings.png",
    response_class=Response,
    responses={200: {"content": {"image/png": {}}, "description": "Rating bar chart"}},
)
def ratings_chart(book_id: int, n: Annotated[int, Query(ge=1, le=20)] = 5) -> Response:
    png = rating_chart([(i % 5) + 1 for i in range(n)])
    return Response(content=png, media_type="image/png", headers={"Cache-Control": "public, max-age=300"})


c = TestClient(app)
r = c.get("/books/1/ratings.png?n=5")
print(r.status_code, r.headers["content-type"], r.headers["content-length"], r.content[:8])
open("chart.png", "wb").write(r.content)
print(c.get("/books/1/ratings.png?n=0").status_code)
print(c.get("/openapi.json").json()["paths"]["/books/{book_id}/ratings.png"]["get"]["responses"]["200"])

200 image/png 122 b'\x89PNG\r\n\x1a\n'
422
{'description': 'Rating bar chart', 'content': {'image/png': {}}}

curl -s localhost:8000/books/1/ratings.png?n=8 -o ratings.png