STAC API implementation for Birdhouse

This implementation extends stac-fastapi-pgstac by providing the following additional features:

• Custom Queryables
• Custom Collection Summaries
• Settable Router Prefix
• Settable OpenAPI paths

Custom Queryables

The /queryables endpoints enabled by stac-fastapi-pgstac only provide basic information about the STAC items. This includes the property type (string, array, number, etc.) but not much else.

This implementation adds additional postgres functions to help discover more detailed queryables information including minumums and maximums for range properties and enum values for discrete properties.

[!Note] Dates are formatted as RFC 3339 strings and JSON schemas only support minumum/maximum for numeric types so minimum and maximum dates are provided as epoch seconds (in the "minimum" and "maximum" fields) and as RFC 3339 strings in the "description" field.

This also adds the following helper route PATCH /queryables which will update the queryables stored in the database with up to date information from all items stored in the database.

We recommend that you update the queryables after you add/remove/update any items in the database.

Custom queryables are enabled by default. To disable this feature and only use the queryables provided by stac-fastapi-pgstac, set the STAC_DEFAULT_QUERYABLES environment variable to 1.

sh export STAC_DEFAULT_QUERYABLES=1

Custom Collection Summaries

Collections in STAC are strongly recommended to provide summaries and extents of the items they contain. This includes the temporal and spatial extents of the whole collection as well as the minumums and maximums for range properties and enum values for discrete properties of items.

These values are not updated automatically so this implementation adds additional postgres functions to help keep these collection summaries and extents up to date.

This also adds the following helper route PATCH /summaries which will update the collection summaries and extents stored in the database with up to date information from all items stored in the database.

[!Note] These functions will only update the first extent value which defines the extent of the whole collection, additional extents that describe subsets of the collection will not be modified.

Custom summaries are enabled by default. To disable this feature and set the STAC_DEFAULT_SUMMARIES environment variable to 1:

sh export STAC_DEFAULT_SUMMARIES=1

Settable Router Prefix

To set a custom router prefix, set the ROUTER_PREFIX environment variable.

For example, the following access the same route:

With no router prefix set:

GET /collections

With a custom router prefix set to /my-prefix:

GET /my-prefix/collections

Settable OpenAPI paths

To set a custom path for the OpenAPI routes set the following environment variables:

• OPENAPI_URL
  • default: /api
  • returns a description of this API in JSON format
• DOCS_URL
  • default: /api.html
  • returns a description of this API in HTML format

[!NOTE] Note that other environment variables can be used to set other settings according to the FastAPI documentation and the STAC-FastAPI documentation

Contributing

Ensure that the pre-commit checks are installed so that you make sure that your code changes conform to the expected style for this project.

pip install pre-commit pre-commit install

Releasing

Before making a new release:

pip install bump2version bump2version <part>

Where <part> is one of major, minor, patch to determine which version number is updated. This project uses semantic versioning.