feat: paginate collection (#26)

To address performance and scalability issues with the `/collections`
endpoint under high collection volume, I integrated pagination support
using the `CollectionPaginationExtension` from `STAC FastAPI`.
The `all_collections()` method now supports `limit` (default: 10) and
`offset` (default: 0) parameters, ensuring the API no longer returns the
full collection list by default.
The response includes pagination metadata with `first`, `next`, and
`previous` links to facilitate navigation.

Author: RitejAyed

stac_fastapi/eodag/app.py

@@ -37,7 +37,16 @@
     create_post_request_model,
     create_request_model,
 )
-from stac_fastapi.extensions.core import FilterExtension, QueryExtension, SortExtension
+from stac_fastapi.extensions.core import (
+    CollectionSearchExtension,
+    FilterExtension,
+    FreeTextExtension,
+    QueryExtension,
+    SortExtension,
+)
+from stac_fastapi.extensions.core.free_text import FreeTextConformanceClasses
+from stac_fastapi.extensions.core.query import QueryConformanceClasses
+from stac_fastapi.extensions.core.sort import SortConformanceClasses
 
 from stac_fastapi.eodag.config import get_settings
 from stac_fastapi.eodag.core import EodagCoreClient
@@ -47,10 +56,10 @@
     BaseCollectionOrderClient,
     CollectionOrderExtension,
 )
-from stac_fastapi.eodag.extensions.collection_search import CollectionSearchExtension
 from stac_fastapi.eodag.extensions.data_download import DataDownload
 from stac_fastapi.eodag.extensions.ecmwf import EcmwfExtension
 from stac_fastapi.eodag.extensions.filter import FiltersClient
+from stac_fastapi.eodag.extensions.offset_pagination import OffsetPaginationExtension
 from stac_fastapi.eodag.extensions.pagination import PaginationExtension
 from stac_fastapi.eodag.extensions.stac import (
     ElectroOpticalExtension,
@@ -92,22 +101,56 @@
         EcmwfExtension(),
     ]
 )
-extensions_map = {
-    "collection-search": CollectionSearchExtension(),
-    "pagination": PaginationExtension(),
-    "filter": FilterExtension(client=FiltersClient(stac_metadata_model=stac_metadata_model)),
+
+# search extensions
+search_extensions_map = {
     "query": QueryExtension(),
     "sort": SortExtension(),
-    "collection-order": CollectionOrderExtension(
-        client=BaseCollectionOrderClient(stac_metadata_model=stac_metadata_model)
-    ),
-    "data-download": DataDownload(),
+    "filter": FilterExtension(client=FiltersClient(stac_metadata_model=stac_metadata_model)),
+    "pagination": PaginationExtension(),
+}
+
+# collection_search extensions
+cs_extensions_map = {
+    "query": QueryExtension(conformance_classes=[QueryConformanceClasses.COLLECTIONS]),
+    "offset-pagination": OffsetPaginationExtension(),
+    "collection-search": CollectionSearchExtension(),
+    "free-text": FreeTextExtension(conformance_classes=[FreeTextConformanceClasses.COLLECTIONS]),
 }
 
-if enabled_extensions := os.getenv("ENABLED_EXTENSIONS"):
-    extensions = [extensions_map[extension_name] for extension_name in enabled_extensions.split(",")]
-else:
-    extensions = list(extensions_map.values())
+# item_collection extensions
+itm_col_extensions_map = {
+    "pagination": PaginationExtension(),
+    "sort": SortExtension(conformance_classes=[SortConformanceClasses.ITEMS]),
+}
+
+all_extensions = {
+    **search_extensions_map,
+    **cs_extensions_map,
+    **itm_col_extensions_map,
+    **{
+        "data-download": DataDownload(),
+        "collection-order": CollectionOrderExtension(
+            client=BaseCollectionOrderClient(stac_metadata_model=stac_metadata_model)
+        ),
+    },
+}
+
+
+def get_enabled_extensions(specif_extensions: dict):
+    """
+    Retrieve the list of enabled extensions based on the environment variable `ENABLED_EXTENSIONS`.
+
+    :param specif_extensions: A dictionary mapping extension names to their corresponding objects.
+    :returns: A list of enabled extension objects. If `ENABLED_EXTENSIONS` is not set, all extensions
+              from `specif_extensions` are returned.
+    """
+    if enabled := os.getenv("ENABLED_EXTENSIONS"):
+        return [specif_extensions[name] for name in enabled.split(",") if name in specif_extensions]
+    return list(specif_extensions.values())
+
+
+extensions = get_enabled_extensions(all_extensions)
 
 for e in extensions:
     if isinstance(e, CollectionOrderExtension):
@@ -142,22 +185,23 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
 add_exception_handlers(app)
 app.add_middleware(RequestIDMiddleware)
 
+search_extensions = get_enabled_extensions(search_extensions_map)
 
-search_post_model = create_post_request_model(extensions)
-search_get_model = create_get_request_model(extensions)
+search_post_model = create_post_request_model(search_extensions)
+search_get_model = create_get_request_model(search_extensions)
 
 
 collections_model = create_request_model(
     "CollectionsRequest",
     base_model=EmptyRequest,
-    extensions=[e for e in extensions if isinstance(e, CollectionSearchExtension)],
+    extensions=get_enabled_extensions(cs_extensions_map),
     request_type="GET",
 )
 
 item_collection_model = create_request_model(
     "ItemsRequest",
     base_model=ItemCollectionUri,
-    extensions=[e for e in extensions if isinstance(e, PaginationExtension) or isinstance(e, SortExtension)],
+    extensions=get_enabled_extensions(itm_col_extensions_map),
     request_type="GET",
 )
 

stac_fastapi/eodag/core.py

@@ -23,7 +23,7 @@
 import logging
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, cast
-from urllib.parse import unquote_plus, urljoin
+from urllib.parse import unquote_plus
 
 import attr
 import orjson
@@ -53,6 +53,7 @@
 from stac_fastapi.eodag.errors import NoMatchingProductType, ResponseSearchError
 from stac_fastapi.eodag.models.links import (
     CollectionLinks,
+    CollectionSearchPagingLinks,
     ItemCollectionLinks,
     PagingLinks,
 )
@@ -221,7 +222,8 @@ async def all_collections(
         request: Request,
         bbox: Optional[list[NumType]] = None,
         datetime: Optional[DateTimeType] = None,
-        limit: Optional[int] = None,
+        limit: Optional[int] = 10,
+        offset: Optional[int] = 0,
         q: Optional[str] = None,
         query: Optional[str] = None,
     ) -> Collections:
@@ -232,13 +234,18 @@ async def all_collections(
         :param bbox: Bounding box to filter the collections.
         :param datetime: Date and time range to filter the collections.
         :param limit: Maximum number of collections to return.
+        :param offset: Starting position from which to return collections.
         :param q: Query string to filter the collections.
         :param query: Query string to filter collections.
         :returns: All collections.
         :raises HTTPException: If the unsupported bbox parameter is provided.
         """
         base_url = get_base_url(request)
 
+        next_link: Optional[dict[str, Any]] = None
+        prev_link: Optional[dict[str, Any]] = None
+        first_link: dict[str, Any] = {"body": {"limit": limit, "offset": 0}}
+
         # get provider filter
         provider = None
         if query:
@@ -278,21 +285,41 @@ async def all_collections(
                 ).intersection(bbox_geom)
             ]
 
+        limit = limit if limit is not None else 10
+        offset = offset if offset is not None else 0
+
+        paged_collections = collections[offset : offset + limit]
+
+        total = len(collections)
+
+        if offset + limit < total:
+            next_link = {"body": {"limit": limit, "offset": offset + limit}}
+
+        if offset > 0:
+            prev_link = {"body": {"limit": limit, "offset": max(0, offset - limit)}}
+
         links = [
-            {
-                "rel": Relations.self.value,
-                "type": MimeTypes.json,
-                "href": urljoin(base_url, "collections"),
-                "title": "Collections",
-            },
             {
                 "rel": Relations.root,
                 "type": MimeTypes.json,
                 "href": base_url,
                 "title": get_settings().stac_fastapi_title,
             },
         ]
-        return Collections(collections=collections[:limit] or [], links=links)
+        extension_names = [type(ext).__name__ for ext in self.extensions]
+
+        paging_links = CollectionSearchPagingLinks(
+            request=request, next=next_link, prev=prev_link, first=first_link
+        ).get_links(extensions=extension_names)
+
+        links.extend(paging_links)
+
+        return Collections(
+            collections=paged_collections or [],
+            links=links,
+            numberMatched=total,
+            numberReturned=len(paged_collections),
+        )
 
     async def get_collection(self, collection_id: str, request: Request, **kwargs: Any) -> Collection:
         """

stac_fastapi/eodag/extensions/collection_search.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025, CS GROUP - France, https://www.cs-soprasteria.com
+#
+# This file is part of stac-fastapi-eodag project
+#     https://www.github.com/CS-SI/stac-fastapi-eodag
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Offset pagination extension."""
+
+from typing import Annotated
+
+import attr
+from fastapi import Query
+from pydantic import NonNegativeInt
+from stac_fastapi.extensions.core.pagination import OffsetPaginationExtension as BaseOffsetPaginationExtension
+from stac_fastapi.types.search import APIRequest
+
+
+@attr.s
+class GETOffsetPagination(APIRequest):
+    """Offset pagination for GET requests."""
+
+    offset: Annotated[NonNegativeInt, Query()] = attr.ib(default=0)
+
+
+@attr.s
+class OffsetPaginationExtension(BaseOffsetPaginationExtension):
+    """Customized Offset Pagination.
+
+    This extension overrides the default GET pagination class to apply a modified
+    offset parameter definition. Specifically, we enforce a non-negative integer
+    constraint and potentially adjust default values.
+
+    A new GET class (`GETOffsetPagination`) is defined to include these changes,
+    so they are correctly reflected in both the request validation and the
+    generated OpenAPI schema.
+    """
+
+    GET = GETOffsetPagination