add migration guide

docs/mkdocs.yml

@@ -74,6 +74,8 @@ nav:
           - search: api/stac_fastapi/types/search.md
           - stac: api/stac_fastapi/types/stac.md
           - version: api/stac_fastapi/types/version.md
+  - Migration Guides:
+    - v2.5 -> v3.0: migrations/v3.0.0.md
   - Performance Benchmarks: benchmarks.html
   - Development - Contributing: "contributing.md"
   - Release Notes: "release-notes.md"

docs/src/migrations/v3.0.0.md

@@ -0,0 +1,163 @@
+
+# stac-fastapi v3.0 Migration Guide
+
+This document aims to help you update your application from **stac-fastapi** 2.5 to 3.0.0.
+
+## Dependencies
+
+- **pydantic~=2.0**
+- **fastapi>=0.111**
+- **stac-pydantic~=3.1**
+
+Most of the **stac-fastapi's** dependencies have been upgraded. Moving from pydantic v1 to v2 is mostly the one update bringing most breaking changes (see https://docs.pydantic.dev/latest/migration/).
+
+In addition to pydantic v2 update, `stac-pydantic` has been updated to better match the STAC and STAC-API specifications (see https://github.com/stac-utils/stac-pydantic/blob/main/CHANGELOG.md#310-2024-05-21)
+
+
+## Deprecation
+
+* the `ContextExtension` have been removed (see https://github.com/stac-utils/stac-pydantic/pull/138) and was replaced by optional `NumberMatched` and `NumberReturned` attributes, defined by the OGC features specification.
+
+* `stac_fastapi.api.config_openapi` method was removed (see https://github.com/stac-utils/stac-fastapi/pull/523)
+
+* passing `response_class` in `stac_fastapi.api.routes.create_async_endpoint` is now deprecated. The response class now has to be set when registering the endpoint to the application (see https://github.com/stac-utils/stac-fastapi/issues/461)
+
+* `PostFieldsExtension.filter_fields` property has been removed.
+
+## Middlewares configuration
+
+The `StacApi.middlewares` attribute has been updated to accept a list of `starlette.middleware.Middleware`. This enables dynamic configuration of middlewares (see https://github.com/stac-utils/stac-fastapi/pull/442).
+
+```python
+# before
+class myMiddleware(mainMiddleware):
+    option1 = option1
+    option2 = option2
+
+stac = StacApi(
+    middlewares=[
+        myMiddleware,
+    ]
+)
+
+# now
+stac = StacApi(
+    middlewares=[
+        Middleware(myMiddleware, option1, option2),
+    ]
+)
+```
+
+## Request Models
+
+In stac-fastapi v2.0, users could already customize both GET/POST search request models. For v3.0, we've added more attributes to enable other endpoints customization:
+
+- `collections_get_request_model`: GET request model for the `/collections` endpoint (default to `EmptyRequest`)
+- `collection_get_request_model`: GET request model for the `/collections/{collection_id}` endpoint (default to `stac_fastapi.api.models.CollectionUri`)
+- `items_get_request_model`: GET request model for the `/collections/{collection_id}/items` endpoint (default to `stac_fastapi.api.models.ItemCollectionUri`)
+- `item_get_request_model`: GET request model for the `/collections/{collection_id}/items/{item_id}` endpoint (default to `stac_fastapi.api.models.ItemUri`)
+
+```python
+# before
+getSearchModel = create_request_model(
+    model_name="SearchGetRequest",
+    base_model=BaseSearchGetRequest
+    extensions=[...],
+    request_type="GET"
+)
+stac = StacApi(
+    search_get_request_model=getSearchModel,
+    search_post_request_model=...,
+)
+
+# now
+@dataclass
+class CollectionsRequest(APIRequest):
+    user: str = Query(...)
+
+stac = StacApi(
+    search_get_request_model=getSearchModel,
+    search_post_request_model=postSearchModel,
+        collections_get_request_model=CollectionsRequest,
+        collection_get_request_model=...,
+        items_get_request_model=...,
+        item_get_request_model=...,
+)
+```
+
+## Filter extension
+
+`default_includes` attribute has been removed from the `ApiSettings` object. If you need `defaults` includes you can overwrite the `FieldExtension` models (see https://github.com/stac-utils/stac-fastapi/pull/706).
+
+```python
+# before
+stac = StacApi(
+    extensions=[
+        FieldsExtension()
+    ]
+)
+
+# now
+class PostFieldsExtension(requests.PostFieldsExtension):
+    include: Optional[Set[str]] = Field(
+        default_factory=lambda: {
+            "id",
+            "type",
+            "stac_version",
+            "geometry",
+            "bbox",
+            "links",
+            "assets",
+            "properties.datetime",
+            "collection",
+        }
+    )
+    exclude: Optional[Set[str]] = set()
+
+
+class FieldsExtensionPostRequest(BaseModel):
+    """Additional fields and schema for the POST request."""
+
+    fields: Optional[PostFieldsExtension] = Field(PostFieldsExtension())
+
+
+class FieldsExtension(FieldsExtensionBase):
+    """Override the POST model"""
+
+    POST = FieldsExtensionPostRequest
+
+
+from stac_fastapi.api.app import StacApi
+
+stac = StacApi(
+    extensions=[
+        FieldsExtension()
+    ]
+)
+```
+
+## Pagination extension
+
+In stac-fastapi v3.0, we removed the `pagination_extension` attribute in `stac_fastapi.api.app.StacApi`. This attribute was used within the `register_get_item_collection` to update the request model for the `/collections/{collection_id}/items` endpoint.
+
+It's now up to the user to create the request model and use the `items_get_request_model=` attribute in the StacApi object.
+
+```python
+# before
+stac=StacApi(
+    pagination_extension=TokenPaginationExtension,
+    extension=[TokenPaginationExtension]
+)
+
+# now
+items_get_request_model = create_request_model(
+    "ItemCollectionURI",
+    base_model=ItemCollectionUri,
+    mixins=[TokenPaginationExtension().GET],
+)
+
+stac=StacApi(
+    extension=[TokenPaginationExtension],
+    items_get_request_model=items_get_request_model,
+)
+```