stac-fastapi.static 0.0.4

An implementation of STAC API based on the FastAPI framework using a static catalog as backend.

stac-fastapi-static

Static STAC Catalog backend for stac-fastapi, the FastAPI implementation of the STAC API spec.

This project is still in (late) initial development phase.

Overview

stac-fastapi-static is a stac-fastapi backend built in FastAPI. It provides an implementation of the STAC API spec ready to be deployed on top of a static STAC catalog. The target backend static catalog can be remotely hosted (by any static HTTP server) or locally hosted (filesystem).

STAC API Support

Extension	Support
Core	Yes
Item Search	Yes

STAC API Extensions Support

From STAC API Extensions page :

Extension	Support
Query	No - Not intended : "It is recommended to implement the Filter Extension instead of the Query Extension" Query Extension homepage
Sort	No - Not intended : Hard to implement in an performant enough manner to be viable with a static catalog
Transaction and Collection Transaction	No - Not intended - Feasible
Fields	No - Not intended - Feasible
Filter	Yes
Collection Search	Yes
Language	No - Maybe soon ? - Feasible

Use Cases & Limitations

The appeal of instanciating a STAC API directly on top of a static catalog is obvious. However the performance issue will make or break this project.

Our goal is to provide viable performances on a 500,000 item static catalog.

Design Choices, Performances and limitations

Inherently, building an API on a 100,000s items static STAC catalog is going to be far slower than on a database backed catalog, however the STAC specs defines constraints (and recommendations) that can be abused to design a performant enough API.

todo : Include data plots from locust tests on big catalogs.

Usage

Prefered Method : Containerized API Server

docker run \
	--env-file .env \
	--env app_port=8000 \
	--env environment=prod \
	--env log_level=warning \
	--env catalog_href=<catalog_url> \
	--volume /tmp:/tmp \
	--publish 8000:8000 \
	ghcr.io/fntb/stac-fastapi-static:latest

Note :

• --volume <path-to-catalog-directory>:/app/catalog/ and --env catalog_href=file:///app/catalog/catalog.json to serve a local catalog
• See the Justfile.

Alternative Method : Python Packaged API Server

Install, create a dotenv configuration file (or pass configuration options as env variables), and run :

pip install stac-fastapi-static

# either
touch .env
stac-fastapi-static

# or
<option>=<value> stac-fastapi-static

Configuration Options

See the Settings model.

Amongst other :

class Settings(ApiSettings):
    # https://docs.pydantic.dev/latest/concepts/pydantic_settings/

    ...

    app_host: str = "0.0.0.0"
    app_port: int = 8000
    root_path: str = ""

    ...

Test and Develop

just --list

Or see the Justfile.

Release checklist : bump version, build, commit, tag, push, publish to pypi and ghcr.

History

stac-fastapi-static is being actively developped at the OPGC an observatory for the sciences of the universe (OSU) belonging to the CNRS and the UCA by its main author Pierre Fontbonne @fntb. It was originally reverse engineered from the stac-fastapi-pgstac backend by developmentseed.

License

OPEN LICENCE 2.0