stac-fastapi v4.0 Migration Guide¶

This document aims to help you update your application from stac-fastapi 3.0 to 4.0

CHANGELOG¶

Changed¶

use string type instead of python datetime.datetime for datetime parameter in BaseSearchGetRequest, ItemCollectionUri and BaseCollectionSearchGetRequest GET models
rename filter to filter_expr for FilterExtensionGetRequest and FilterExtensionPostRequest attributes to avoid conflict with python filter method
remove post_request_model attribute in BaseCoreClient and AsyncBaseCoreClient
remove python3.8 support

Fixed¶

Support multiple proxy servers in the forwarded header in ProxyHeaderMiddleware (#782)

Datetime type in GET request models¶

While the POST request models are created using stac-pydantic, the GET request models are python attrs classes (~dataclasses). In 4.0, we've decided to change how the datetime attribute was defined in BaseSearchGetRequest, ItemCollectionUri and BaseCollectionSearchGetRequest models to match the datetime definition/validation done by the pydantic model. This mostly mean that the datetime attribute forwarded to the GET endpoints will now be of type string (forwarded from the user input).

from starlette.testclient import TestClient
from stac_fastapi.api.app import StacApi
from stac_fastapi.types.config import ApiSettings
from stac_fastapi.types.core import BaseCoreClient

class DummyCoreClient(BaseCoreClient):
    def all_collections(self, *args, **kwargs):
        raise NotImplementedError

    def get_collection(self, *args, **kwargs):
        raise NotImplementedError

    def get_item(self, *args, **kwargs):
        raise NotImplementedError

    def get_search(self, *args, datetime = None, **kwargs):
        # Return True if datetime is a string
        return isinstance(datetime, str)

    def post_search(self, *args, **kwargs):
        raise NotImplementedError

    def item_collection(self, *args, **kwargs):
        raise NotImplementedError

api = StacApi(
    settings=ApiSettings(enable_response_models=False),
    client=DummyCoreClient(),
    extensions=[],
)


# before
with TestClient(api.app) as client:
    response = client.get(
        "/search",
        params={
            "datetime": "2020-01-01T00:00:00.00001Z",
        },
    )
    assert response.json() == False

# now
with TestClient(api.app) as client:
    response = client.get(
        "/search",
        params={
            "datetime": "2020-01-01T00:00:00.00001Z",
        },
    )
    assert response.json() == True

Start/End dates¶

Following stac-pydantic's Search model, we've added class attributes to easily retrieve the parsed dates:

from stac_fastapi.types.search import BaseSearchGetRequest

# Interval
search = BaseSearchGetRequest(datetime="2020-01-01T00:00:00.00001Z/2020-01-02T00:00:00.00001Z")

search.parse_datetime()
>>> (datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc), datetime.datetime(2020, 1, 2, 0, 0, 0, 10, tzinfo=datetime.timezone.utc))

search.start_date
>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

search.end_date
>>> datetime.datetime(2020, 1, 2, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

# Single date
search = BaseSearchGetRequest(datetime="2020-01-01T00:00:00.00001Z")

search.parse_datetime()
>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

search.start_date
>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

search.end_date
>>> None

Filter extension¶

We've renamed the filter attribute to filter_expr in the FilterExtensionGetRequest and FilterExtensionPostRequest models to avoid any conflict with python filter method. This change means GET endpoints with the filter extension enabled will receive filter_expr= option instead of filter=. Same for POST endpoints where the body will now have a .filter_expr instead of a filter attribute.

Note: This change does not affect the input because we use aliases.

from starlette.testclient import TestClient
from stac_fastapi.api.app import StacApi
from stac_fastapi.api.models import create_get_request_model, create_post_request_model
from stac_fastapi.extensions.core import FilterExtension
from stac_fastapi.types.config import ApiSettings
from stac_fastapi.types.core import BaseCoreClient

class DummyCoreClient(BaseCoreClient):
    def all_collections(self, *args, **kwargs):
        raise NotImplementedError

    def get_collection(self, *args, **kwargs):
        raise NotImplementedError

    def get_item(self, *args, **kwargs):
        raise NotImplementedError

    def get_search(self, *args, **kwargs):
        return kwargs

    def post_search(self, *args, **kwargs):
        return args[0].model_dump()

    def item_collection(self, *args, **kwargs):
        raise NotImplementedError

extensions = [FilterExtension()]
api = StacApi(
    settings=ApiSettings(enable_response_models=False),
    client=DummyCoreClient(),
    extensions=extensions,
    search_get_request_model=create_get_request_model(extensions),
    search_post_request_model=create_post_request_model(extensions),
)


# before
with TestClient(api.app) as client:
    response = client.post(
        "/search",
        json={
            "filter": {"op": "=", "args": [{"property": "test_property"}, "test-value"]},
        },
    )
    assert response.json()["filter"]

    response = client.get(
        "/search",
        params={
            "filter": "id='item_id' AND collection='collection_id'",
        },
    )
    assert response.json()["filter"]

# now
with TestClient(api.app) as client:
    response = client.post(
        "/search",
        json={
            "filter": {"op": "=", "args": [{"property": "test_property"}, "test-value"]},
        },
    )
    assert response.json()["filter_expr"]

    response = client.get(
        "/search",
        params={
            "filter": "id='item_id' AND collection='collection_id'",
        },
    )
    assert response.json()["filter_expr"]