|
| 1 | + |
| 2 | +# stac-fastapi v4.0 Migration Guide |
| 3 | + |
| 4 | +This document aims to help you update your application from **stac-fastapi** 3.0 to 4.0 |
| 5 | + |
| 6 | +## CHANGELOG |
| 7 | +### Changed |
| 8 | + |
| 9 | +* use `string` type instead of python `datetime.datetime` for datetime parameter in `BaseSearchGetRequest`, `ItemCollectionUri` and `BaseCollectionSearchGetRequest` GET models |
| 10 | +* rename `filter` to `filter_expr` for `FilterExtensionGetRequest` and `FilterExtensionPostRequest` attributes to avoid conflict with python filter method |
| 11 | +* remove `post_request_model` attribute in `BaseCoreClient` and `AsyncBaseCoreClient` |
| 12 | +* remove `python3.8` support |
| 13 | + |
| 14 | +### Fixed |
| 15 | + |
| 16 | +* Support multiple proxy servers in the `forwarded` header in `ProxyHeaderMiddleware` ([#782](https://github.com/stac-utils/stac-fastapi/pull/782)) |
| 17 | + |
| 18 | +## Datetime type in GET request models |
| 19 | + |
| 20 | +While the POST request models are created using stac-pydantic, the GET request models are python `attrs` classes (~dataclasses). |
| 21 | +In 4.0, we've decided to change how the `datetime` attribute was defined in `BaseSearchGetRequest`, `ItemCollectionUri` and `BaseCollectionSearchGetRequest` models to match |
| 22 | +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). |
| 23 | + |
| 24 | +```python |
| 25 | +from starlette.testclient import TestClient |
| 26 | +from stac_fastapi.api.app import StacApi |
| 27 | +from stac_fastapi.types.config import ApiSettings |
| 28 | +from stac_fastapi.types.core import BaseCoreClient |
| 29 | + |
| 30 | +class DummyCoreClient(BaseCoreClient): |
| 31 | + def all_collections(self, *args, **kwargs): |
| 32 | + raise NotImplementedError |
| 33 | + |
| 34 | + def get_collection(self, *args, **kwargs): |
| 35 | + raise NotImplementedError |
| 36 | + |
| 37 | + def get_item(self, *args, **kwargs): |
| 38 | + raise NotImplementedError |
| 39 | + |
| 40 | + def get_search(self, *args, datetime = None, **kwargs): |
| 41 | + # Return True if datetime is a string |
| 42 | + return isinstance(datetime, str) |
| 43 | + |
| 44 | + def post_search(self, *args, **kwargs): |
| 45 | + raise NotImplementedError |
| 46 | + |
| 47 | + def item_collection(self, *args, **kwargs): |
| 48 | + raise NotImplementedError |
| 49 | + |
| 50 | +api = StacApi( |
| 51 | + settings=ApiSettings(enable_response_models=False), |
| 52 | + client=DummyCoreClient(), |
| 53 | + extensions=[], |
| 54 | +) |
| 55 | + |
| 56 | + |
| 57 | +# before |
| 58 | +with TestClient(api.app) as client: |
| 59 | + response = client.get( |
| 60 | + "/search", |
| 61 | + params={ |
| 62 | + "datetime": "2020-01-01T00:00:00.00001Z", |
| 63 | + }, |
| 64 | + ) |
| 65 | + assert response.json() == False |
| 66 | + |
| 67 | +# now |
| 68 | +with TestClient(api.app) as client: |
| 69 | + response = client.get( |
| 70 | + "/search", |
| 71 | + params={ |
| 72 | + "datetime": "2020-01-01T00:00:00.00001Z", |
| 73 | + }, |
| 74 | + ) |
| 75 | + assert response.json() == True |
| 76 | +``` |
| 77 | + |
| 78 | +#### Start/End dates |
| 79 | + |
| 80 | +Following stac-pydantic's `Search` model, we've added class attributes to easily retrieve the `parsed` dates: |
| 81 | + |
| 82 | +```python |
| 83 | +from stac_fastapi.types.search import BaseSearchGetRequest |
| 84 | + |
| 85 | +# Interval |
| 86 | +search = BaseSearchGetRequest(datetime="2020-01-01T00:00:00.00001Z/2020-01-02T00:00:00.00001Z") |
| 87 | + |
| 88 | +search.parse_datetime() |
| 89 | +>>> (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)) |
| 90 | + |
| 91 | +search.start_date |
| 92 | +>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc) |
| 93 | + |
| 94 | +search.end_date |
| 95 | +>>> datetime.datetime(2020, 1, 2, 0, 0, 0, 10, tzinfo=datetime.timezone.utc) |
| 96 | + |
| 97 | +# Single date |
| 98 | +search = BaseSearchGetRequest(datetime="2020-01-01T00:00:00.00001Z") |
| 99 | + |
| 100 | +search.parse_datetime() |
| 101 | +>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc) |
| 102 | + |
| 103 | +search.start_date |
| 104 | +>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc) |
| 105 | + |
| 106 | +search.end_date |
| 107 | +>>> None |
| 108 | +``` |
| 109 | + |
| 110 | +## Filter extension |
| 111 | + |
| 112 | +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. |
| 113 | + |
| 114 | +Note: This change does not affect the `input` because we use `aliases`. |
| 115 | + |
| 116 | +```python |
| 117 | +from starlette.testclient import TestClient |
| 118 | +from stac_fastapi.api.app import StacApi |
| 119 | +from stac_fastapi.api.models import create_get_request_model, create_post_request_model |
| 120 | +from stac_fastapi.extensions.core import FilterExtension |
| 121 | +from stac_fastapi.types.config import ApiSettings |
| 122 | +from stac_fastapi.types.core import BaseCoreClient |
| 123 | + |
| 124 | +class DummyCoreClient(BaseCoreClient): |
| 125 | + def all_collections(self, *args, **kwargs): |
| 126 | + raise NotImplementedError |
| 127 | + |
| 128 | + def get_collection(self, *args, **kwargs): |
| 129 | + raise NotImplementedError |
| 130 | + |
| 131 | + def get_item(self, *args, **kwargs): |
| 132 | + raise NotImplementedError |
| 133 | + |
| 134 | + def get_search(self, *args, **kwargs): |
| 135 | + return kwargs |
| 136 | + |
| 137 | + def post_search(self, *args, **kwargs): |
| 138 | + return args[0].model_dump() |
| 139 | + |
| 140 | + def item_collection(self, *args, **kwargs): |
| 141 | + raise NotImplementedError |
| 142 | + |
| 143 | +extensions = [FilterExtension()] |
| 144 | +api = StacApi( |
| 145 | + settings=ApiSettings(enable_response_models=False), |
| 146 | + client=DummyCoreClient(), |
| 147 | + extensions=extensions, |
| 148 | + search_get_request_model=create_get_request_model(extensions), |
| 149 | + search_post_request_model=create_post_request_model(extensions), |
| 150 | +) |
| 151 | + |
| 152 | + |
| 153 | +# before |
| 154 | +with TestClient(api.app) as client: |
| 155 | + response = client.post( |
| 156 | + "/search", |
| 157 | + json={ |
| 158 | + "filter": {"op": "=", "args": [{"property": "test_property"}, "test-value"]}, |
| 159 | + }, |
| 160 | + ) |
| 161 | + assert response.json()["filter"] |
| 162 | + |
| 163 | + response = client.get( |
| 164 | + "/search", |
| 165 | + params={ |
| 166 | + "filter": "id='item_id' AND collection='collection_id'", |
| 167 | + }, |
| 168 | + ) |
| 169 | + assert response.json()["filter"] |
| 170 | + |
| 171 | +# now |
| 172 | +with TestClient(api.app) as client: |
| 173 | + response = client.post( |
| 174 | + "/search", |
| 175 | + json={ |
| 176 | + "filter": {"op": "=", "args": [{"property": "test_property"}, "test-value"]}, |
| 177 | + }, |
| 178 | + ) |
| 179 | + assert response.json()["filter_expr"] |
| 180 | + |
| 181 | + response = client.get( |
| 182 | + "/search", |
| 183 | + params={ |
| 184 | + "filter": "id='item_id' AND collection='collection_id'", |
| 185 | + }, |
| 186 | + ) |
| 187 | + assert response.json()["filter_expr"] |
| 188 | +``` |
| 189 | + |
| 190 | + |
0 commit comments