initial implementation of router composition for products

Author: austin-sidekick

conftest.py

@@ -5,7 +5,7 @@
 from fastapi.testclient import TestClient
 from pytest import Parser, fixture
 
-from stapi_fastapi.api import StapiRouter
+from stapi_fastapi.main_router import MainRouter
 from stapi_fastapi_test_backend import TestBackend
 
 T = TypeVar("T")
@@ -38,7 +38,7 @@ def stapi_client(stapi_backend, base_url: str) -> YieldFixture[TestClient]:
     app = FastAPI()
 
     app.include_router(
-        StapiRouter(backend=stapi_backend).router,
+        MainRouter(backend=stapi_backend).router,
         prefix="",
     )
 

stapi_fastapi/__dev__.py

@@ -13,8 +13,8 @@
     print("install uvicorn and pydantic-settings to use the dev server", file=stderr)
     exit(1)
 
-from stapi_fastapi.api import StapiRouter
-
+from stapi_fastapi.main_router import MainRouter
+from stapi_fastapi.routers.umbra_spotlight_router import umbra_spotlight_router
 
 class DevSettings(BaseSettings):
     port: int = 8000
@@ -34,8 +34,19 @@ def validate_backend(cls, value: str):
 
 settings = DevSettings()
 backend = settings.backend_name()
+
+# Compose the router
+main_router = MainRouter()
+main_router.include_router(umbra_spotlight_router, prefix="/umbra_spotlight")
+
 app = FastAPI(debug=True)
-app.include_router(StapiRouter(backend).router)
+app.include_router(main_router)
+
+# Define a root endpoint
+# TODO: do I need this?
+@app.get("/")
+async def read_root():
+    return {"message": "Welcome to STAPI AKA STAC to the Future AKA STAC-ish Order API"}
 
 
 def cli():

stapi_fastapi/exceptions.py

@@ -1,5 +1,9 @@
 from typing import Any, Mapping
+from fastapi import HTTPException
 
+class StapiException(HTTPException):
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(status_code, detail)
 
 class ConstraintsException(Exception):
     detail: Mapping[str, Any] | None

stapi_fastapi/api.py stapi_fastapi/main_router.pystapi_fastapi/api.py renamed to stapi_fastapi/main_router.py

@@ -4,7 +4,7 @@
 
 from stapi_fastapi.backend import StapiBackend
 from stapi_fastapi.constants import TYPE_GEOJSON, TYPE_JSON
-from stapi_fastapi.exceptions import ConstraintsException, NotFoundException
+from stapi_fastapi.exceptions import StapiException, ConstraintsException, NotFoundException
 from stapi_fastapi.models.opportunity import (
     OpportunityCollection,
     OpportunityRequest,
@@ -15,14 +15,12 @@
 from stapi_fastapi.models.shared import HTTPException as HTTPExceptionModel
 from stapi_fastapi.models.shared import Link
 
-
-class StapiException(HTTPException):
-    def __init__(self, status_code: int, detail: str) -> None:
-        super().__init__(status_code, detail)
-
-
-class StapiRouter:
-    NAME_PREFIX = "stapi"
+"""
+/products/{component router} # router for each product added to main router
+/orders # list all orders
+"""
+class MainRouter:
+    NAME_PREFIX = "main"
     backend: StapiBackend
     openapi_endpoint_name: str
     docs_endpoint_name: str
@@ -56,6 +54,7 @@ def __init__(
             name=f"{self.NAME_PREFIX}:list-products",
             tags=["Product"],
         )
+
         self.router.add_api_route(
             "/products/{product_id}",
             self.product,
@@ -81,6 +80,7 @@ def __init__(
             tags=["Orders"],
             response_model=Order,
         )
+
         self.router.add_api_route(
             "/orders/{order_id}",
             self.get_order,

stapi_fastapi/models/opportunity.py

@@ -8,18 +8,21 @@
 from stapi_fastapi.types.filter import CQL2Filter
 
 
+# GENERIC Python
 # Copied and modified from https://github.com/stac-utils/stac-pydantic/blob/main/stac_pydantic/item.py#L11
 class OpportunityProperties(BaseModel):
     datetime: DatetimeInterval
-    product_id: str
     model_config = ConfigDict(extra="allow")
 
-
-class OpportunityRequest(OpportunityProperties):
+# NOT GENERIC
+class OpportunityRequest(BaseModel):
+    datetime: DatetimeInterval
     geometry: Geometry
+    # TODO: validate the CQL2 filter?
     filter: Optional[CQL2Filter] = None
+    # PHILOSOPH: strict?
 
-
+# GENERIC: Each product needs an opportunity model (constraints/parameters)
 class Opportunity(Feature[Geometry, OpportunityProperties]):
     type: Literal["Feature"] = "Feature"
 

stapi_fastapi/products_router.py

@@ -0,0 +1,52 @@
+# Generic product router factory
+from fastapi import APIRouter, HTTPException, status, Request
+from typing import Dict, Any
+from stapi_fastapi.models.opportunity import OpportunityRequest
+from stapi_fastapi.backend import StapiBackend
+from stapi_fastapi.exceptions import ConstraintsException
+
+"""
+/products[MainRouter]/opportunities
+/products[MainRouter]/parameters
+/products[MainRouter]/order
+"""
+
+def create_products_router(product_id: str, backend: StapiBackend) -> APIRouter:
+    # TODO: map product names to product IDs
+    """
+    Creates a new APIRouter for a specific product type with standardized routes.
+
+    Args:
+        product_id (str): The name of the product type (e.g., 'electronics', 'furniture').
+        backend (StapiBackend): Backend instance implementing the StapiBackend protocol.
+
+    Returns:
+        APIRouter: A FastAPI APIRouter configured for the product type.
+    """
+    # Create a new router for the given product type
+    router = APIRouter(prefix=f"/{product_id}", tags=[product_id.capitalize()])
+
+    @router.get("/opportunities", summary="Get Opportunities for the product")
+    async def get_opportunities(request: Request, search: OpportunityRequest):
+        try:
+            opportunities = await backend.search_opportunities(search, request)
+            return opportunities
+        except ConstraintsException as exc:
+            raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.detail)
+
+    @router.get("/parameters", summary="Get parameters for the product")
+    async def get_product_parameters(request: Request):
+        product = backend.product(product_id, request)
+        if not product:
+            raise HTTPException(status_code=404, detail="Product not found")
+        return {"product_id": product.id, "parameters": product.parameters}
+
+    @router.post("/order", summary="Create an order for the product")
+    async def create_order(request: Request, payload: OpportunityRequest):
+        try:
+            order = await backend.create_order(payload, request)
+            return order
+        except ConstraintsException as exc:
+            raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.detail)
+
+    return router

stapi_fastapi/umbra_spotlight_router.py

@@ -0,0 +1,4 @@
+from routers.products_router import create_products_router
+
+# Create a router for electronics using the base factory function
+umbra_spotlight_router = create_products_router("umbra_spotlight")