stac-fastapi HTML middleware

stac-fastapi middleware to encode responses into HTML documents

---

Source Code: https://github.com/developmentseed/stac-fastapi-html-middleware

---

Install

$ git clone https://github.com/developmentseed/stac-fastapi-html-middleware.git
$ cd stac-fastapi-html-middleware
$ python -m pip install -e .

What

The HTMLRenderMiddleware is designed to intercept responses from stac-fastapi application (json or geojson) and to encode it to HTML responses when:

• the user set f=html query-parameter
• Accept: text/html request's headers is the highest priority

# regular request - return JSON document
$ curl http://127.0.0.1:8000 -s -D - -o /dev/null
HTTP/1.1 200 OK
date: Wed, 26 Mar 2025 11:16:18 GMT
server: uvicorn
content-length: 3001
content-type: application/json

# Ask for html with `Accept` header - return HTML document
$ curl http://127.0.0.1:8000 -s -D - -o /dev/null -H 'accept: text/html'
HTTP/1.1 200 OK
date: Wed, 26 Mar 2025 11:15:38 GMT
server: uvicorn
content-length: 3560
content-type: text/html

# Ask for html with `f=html` QueryParameter - return HTML document
$ curl http://127.0.0.1:8000\?f\=html -s -D - -o /dev/null
HTTP/1.1 200 OK
date: Wed, 26 Mar 2025 11:16:03 GMT
server: uvicorn
content-length: 3569
content-type: text/html

This middleware will also intercept the openapi document from stac-fastapi application to enhance the schemas by adding f=html query-parameter and Accept: text/html available headers.

How

from starlette.middleware import Middleware

from stac_fastapi.api.app import StacApi
from stac_fastapi.html.middleware import HTMLRenderMiddleware

api = StacApi(
    middlewares=[
        Middleware(HTMLRenderMiddleware),
    ],
)

⚠️ You should place the HTMLRenderMiddleware before any compression middleware in the middlewares stack

# NOK
api = StacApi(
    ...
    middlewares=[
        Middleware(BrotliMiddleware),
        Middleware(HTMLRenderMiddleware),
    ],
)
# OK
api = StacApi(
    ...
    middlewares=[
        Middleware(HTMLRenderMiddleware),  # <-- Put the HTML Render middleware before the compression middleware
        Middleware(BrotliMiddleware),
    ],
)

HTML documents

See docs/pages.md for HTML preview

Contribution & Development

See CONTRIBUTING.md

License

See LICENSE

Authors

Created by Development Seed

Changes

See CHANGES.md.