Implement alternative backing for browsable features

Author: moradology

docker-compose.yml

@@ -53,6 +53,7 @@ services:
       - GDAL_DISABLE_READDIR_ON_OPEN=EMPTY_DIR
       - DB_MIN_CONN_SIZE=1
       - DB_MAX_CONN_SIZE=1
+      - BROWSABLE_HIERARCHY_DEFINITION=/app/stac_fastapi/testdata/joplin/hierarchy.json
     ports:
       - "8082:8082"
     volumes:

stac_fastapi/api/stac_fastapi/api/app.py

@@ -6,7 +6,7 @@
 from fastapi import APIRouter, FastAPI
 from fastapi.openapi.utils import get_openapi
 from pydantic import BaseModel
-from stac_pydantic import Children, Collection, Item, ItemCollection
+from stac_pydantic import Catalog, Collection, Item, ItemCollection
 from stac_pydantic.api import ConformanceClasses, LandingPage
 from stac_pydantic.api.collections import Collections
 from stac_pydantic.version import STAC_VERSION
@@ -15,6 +15,7 @@
 from stac_fastapi.api.errors import DEFAULT_STATUS_CODES, add_exception_handlers
 from stac_fastapi.api.models import (
     APIRequest,
+    CatalogUri,
     CollectionUri,
     EmptyRequest,
     GeoJSONResponse,
@@ -31,6 +32,7 @@
 from stac_fastapi.types.core import AsyncBaseCoreClient, BaseCoreClient
 from stac_fastapi.types.extension import ApiExtension
 from stac_fastapi.types.search import BaseSearchGetRequest, BaseSearchPostRequest
+from stac_fastapi.types.stac import Children
 
 
 @attr.s
@@ -261,6 +263,25 @@ def register_get_collection(self):
             ),
         )
 
+    def register_get_catalog(self):
+        """Register get collection endpoint (GET /catalog/{catalog_path}).
+
+        Returns:
+            None
+        """
+        self.router.add_api_route(
+            name="Get Catalog",
+            path="/catalogs/{catalog_path:path}",
+            response_model=Catalog if self.settings.enable_response_models else None,
+            response_class=self.response_class,
+            response_model_exclude_unset=True,
+            response_model_exclude_none=True,
+            methods=["GET"],
+            endpoint=self._create_endpoint(
+                self.client.get_catalog, CatalogUri, self.response_class
+            ),
+        )
+
     def register_get_collection_children(self):
         """Register get collection children endpoint (GET /collection/{collection_id}/children).
 
@@ -332,6 +353,7 @@ def register_core(self):
         self.register_get_collections()
         self.register_get_collection()
         self.register_get_collection_children()
+        self.register_get_catalog()
         self.register_get_item_collection()
 
     def customize_openapi(self) -> Optional[Dict[str, Any]]:

stac_fastapi/api/stac_fastapi/api/models.py

@@ -97,16 +97,23 @@ def create_post_request_model(
     )
 
 
+@attr.s  # type:ignore
+class CatalogUri(APIRequest):
+    """Catalog Path."""
+
+    catalog_path: str = attr.ib(default=Path(..., description="Catalog Path"))
+
+
 @attr.s  # type:ignore
 class CollectionUri(APIRequest):
-    """Delete collection."""
+    """Collection URI."""
 
     collection_id: str = attr.ib(default=Path(..., description="Collection ID"))
 
 
 @attr.s
 class ItemUri(CollectionUri):
-    """Delete item."""
+    """Item URI."""
 
     item_id: str = attr.ib(default=Path(..., description="Item ID"))
 

stac_fastapi/pgstac/stac_fastapi/pgstac/app.py

@@ -1,4 +1,6 @@
 """FastAPI application using PGStac."""
+import json
+
 from fastapi.responses import ORJSONResponse
 
 from stac_fastapi.api.app import StacApi
@@ -16,6 +18,7 @@
 from stac_fastapi.pgstac.extensions import QueryExtension
 from stac_fastapi.pgstac.transactions import TransactionsClient
 from stac_fastapi.pgstac.types.search import PgstacSearch
+from stac_fastapi.types.hierarchy import BrowsableNode, parse_hierarchy
 
 settings = Settings()
 extensions = [
@@ -30,13 +33,18 @@
     TokenPaginationExtension(),
     ContextExtension(),
 ]
+with open(settings.browsable_hierarchy_definition, "r") as definition_file:
+    hierarchy_json = json.load(definition_file)
+    hierarchy_definition: BrowsableNode = parse_hierarchy(hierarchy_json)
 
 post_request_model = create_post_request_model(extensions, base_model=PgstacSearch)
 
 api = StacApi(
     settings=settings,
     extensions=extensions,
-    client=CoreCrudClient(post_request_model=post_request_model),
+    client=CoreCrudClient(
+        post_request_model=post_request_model, hierarchy_definition=hierarchy_definition
+    ),
     response_class=ORJSONResponse,
     search_get_request_model=create_get_request_model(extensions),
     search_post_request_model=post_request_model,

stac_fastapi/sqlalchemy/stac_fastapi/sqlalchemy/app.py

@@ -1,4 +1,6 @@
 """FastAPI application."""
+import json
+
 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 (
@@ -17,6 +19,7 @@
     BulkTransactionsClient,
     TransactionsClient,
 )
+from stac_fastapi.types.hierarchy import BrowsableNode, parse_hierarchy
 
 settings = SqlalchemySettings()
 session = Session.create_from_settings(settings)
@@ -29,14 +32,20 @@
     TokenPaginationExtension(),
     ContextExtension(),
 ]
+with open(settings.browsable_hierarchy_definition, "r") as definition_file:
+    hierarchy_json = json.load(definition_file)
+    hierarchy_definition: BrowsableNode = parse_hierarchy(hierarchy_json)
 
 post_request_model = create_post_request_model(extensions)
 
 api = StacApi(
     settings=settings,
     extensions=extensions,
     client=CoreCrudClient(
-        session=session, extensions=extensions, post_request_model=post_request_model
+        session=session,
+        extensions=extensions,
+        post_request_model=post_request_model,
+        hierarchy_definition=hierarchy_definition,
     ),
     search_get_request_model=create_get_request_model(extensions),
     search_post_request_model=post_request_model,

stac_fastapi/testdata/joplin/hierarchy.json

@@ -0,0 +1,20 @@
+{
+    "children": [{
+        "catalog_id": "joplin",
+        "title": "Joplin Item Catalog",
+        "description": "All joplin items",
+        "children": [],
+        "items": [
+            ["joplin", "fe916452-ba6f-4631-9154-c249924a122d"],
+            ["joplin", "f7f164c9-cfdf-436d-a3f0-69864c38ba2a"],
+            ["joplin", "f734401c-2df0-4694-a353-cdd3ea760cdc"],
+            ["joplin", "f490b7af-0019-45e2-854b-3854d07fd063"],
+            ["joplin", "f2cca2a3-288b-4518-8a3e-a4492bb60b08"],
+            ["joplin", "ea0fddf4-56f9-4a16-8a0b-f6b0b123b7cf"],
+            ["joplin", "e0a02e4e-aa0c-412e-8f63-6f5344f829df"],
+            ["joplin", "da6ef938-c58f-4bab-9d4e-89f6ae667da2"],
+            ["joplin", "d8461d8c-3d2b-4e4e-a931-7ae61ca06dbf"],
+            ["joplin", "d4eccfa2-7d77-4624-9e2a-3f59102285bb"]
+        ]
+    }]
+}

stac_fastapi/types/stac_fastapi/types/config.py

@@ -29,6 +29,9 @@ class ApiSettings(BaseSettings):
     openapi_url: str = "/api"
     docs_url: str = "/api.html"
 
+    # Path to JSON which defines the browsable hierarchy pending backend implementations
+    browsable_hierarchy_definition: Optional[str] = None
+
     class Config:
         """model config (https://pydantic-docs.helpmanual.io/usage/model_config/)."""
 

stac_fastapi/types/stac_fastapi/types/core.py

@@ -14,6 +14,14 @@
 from stac_fastapi.types import stac as stac_types
 from stac_fastapi.types.conformance import BASE_CONFORMANCE_CLASSES
 from stac_fastapi.types.extension import ApiExtension
+from stac_fastapi.types.hierarchy import (
+    BrowsableNode,
+    CatalogNode,
+    CollectionNode,
+    browsable_catalog,
+    browsable_child_link,
+    browsable_item_link,
+)
 from stac_fastapi.types.search import BaseSearchPostRequest
 from stac_fastapi.types.stac import Conformance
 
@@ -302,6 +310,7 @@ class BaseCoreClient(LandingPageMixin, abc.ABC):
     )
     extensions: List[ApiExtension] = attr.ib(default=attr.Factory(list))
     post_request_model = attr.ib(default=BaseSearchPostRequest)
+    hierarchy_definition: Optional[BrowsableNode] = attr.ib(default=None)
 
     def conformance_classes(self) -> List[str]:
         """Generate conformance classes by adding extension conformance to base conformance classes."""
@@ -360,6 +369,20 @@ def landing_page(self, **kwargs) -> stac_types.LandingPage:
                 }
             )
 
+        # Add links for browsable conformance
+        if self.hierarchy_definition is not None:
+            for child in self.hierarchy_definition["children"]:
+                if isinstance(child, CollectionNode):
+                    landing_page["links"].append(
+                        browsable_child_link(child, urljoin(base_url, "collections"))
+                    )
+                if isinstance(child, CatalogNode):
+                    landing_page["links"].append(
+                        browsable_child_link(child, urljoin(base_url, "catalogs"))
+                    )
+            for item in self.hierarchy_definition["items"]:
+                landing_page["links"].append(browsable_item_link(item, base_url))
+
         # Add OpenAPI URL
         landing_page["links"].append(
             {
@@ -487,6 +510,23 @@ def get_collection_children(
         """
         ...
 
+    def get_catalog(self, catalog_path: str, **kwargs) -> stac_types.Catalog:
+        """Get collection by id.
+
+        Called with `GET /catalogs/{catalog_path}`.
+
+        Args:
+            catalog_path: The full path of the catalog in the browsable hierarchy.
+
+        Returns:
+            Catalog.
+        """
+        split_path = catalog_path.split("/")
+        remaining_hierarchy = self.hierarchy_definition
+        for fork in split_path:
+            remaining_hierarchy = remaining_hierarchy[fork]
+        return browsable_catalog(catalog_path)
+
     @abc.abstractmethod
     def item_collection(
         self, collection_id: str, limit: int = 10, token: str = None, **kwargs
@@ -519,6 +559,7 @@ class AsyncBaseCoreClient(LandingPageMixin, abc.ABC):
     )
     extensions: List[ApiExtension] = attr.ib(default=attr.Factory(list))
     post_request_model = attr.ib(default=BaseSearchPostRequest)
+    hierarchy_definition: Optional[BrowsableNode] = attr.ib(default=None)
 
     def conformance_classes(self) -> List[str]:
         """Generate conformance classes by adding extension conformance to base conformance classes."""
@@ -552,6 +593,8 @@ async def landing_page(self, **kwargs) -> stac_types.LandingPage:
             conformance_classes=self.conformance_classes(),
             extension_schemas=extension_schemas,
         )
+
+        # Add Collections links
         collections = await self.all_collections(request=kwargs["request"])
         for collection in collections["collections"]:
             landing_page["links"].append(
@@ -563,6 +606,20 @@ async def landing_page(self, **kwargs) -> stac_types.LandingPage:
                 }
             )
 
+        # Add links for browsable conformance
+        if self.hierarchy_definition is not None:
+            for child in self.hierarchy_definition["children"]:
+                if "collection_id" in child:
+                    landing_page["links"].append(
+                        browsable_child_link(child, urljoin(base_url, "collections"))
+                    )
+                if "catalog_id" in child:
+                    landing_page["links"].append(
+                        browsable_child_link(child, urljoin(base_url, "catalogs"))
+                    )
+            for item in self.hierarchy_definition["items"]:
+                landing_page["links"].append(browsable_item_link(item, base_url))
+
         # Add OpenAPI URL
         landing_page["links"].append(
             {
@@ -694,6 +751,29 @@ async def get_collection_children(
         """
         ...
 
+    async def get_catalog(self, catalog_path: str, **kwargs) -> stac_types.Catalog:
+        """Get collection by id.
+
+        Called with `GET /catalogs/{catalog_path}`.
+
+        Args:
+            catalog_path: The full path of the catalog in the browsable hierarchy.
+
+        Returns:
+            Catalog.
+        """
+        request: Request = kwargs["request"]
+        base_url = str(request.base_url)
+        split_path = catalog_path.split("/")
+        remaining_hierarchy = self.hierarchy_definition
+        for fork in split_path:
+            remaining_hierarchy = next(
+                node
+                for node in remaining_hierarchy["children"]
+                if node["catalog_id"] == fork
+            )
+        return browsable_catalog(remaining_hierarchy, base_url).dict(exclude_unset=True)
+
     @abc.abstractmethod
     async def item_collection(
         self, collection_id: str, limit: int = 10, token: str = None, **kwargs