add support for order statuses endpoints

Author: Phil Varner

CHANGELOG.md

@@ -6,6 +6,35 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 
+## [0.4.0] - 2024-12-11
+
+### Added
+
+- Endpoint `/orders/{order_id}/statuses` supporting `GET` for retrieving statuses. The entity returned by this conforms
+  to the change proposed in [stapi-spec#239](https://github.com/stapi-spec/stapi-spec/pull/239).
+
+- Endpoint `/orders/{order_id}/statuses` supporting `POST` for updating current status
+
+### Changed
+
+- OrderRequest renamed to OrderPayload
+
+### Deprecated
+
+none
+
+### Removed
+
+none
+
+### Fixed
+
+none
+
+### Security
+
+none
+
 ## [0.4.0] - 2024-12-11
 
 ### Added
@@ -44,6 +73,8 @@ none
 
 - OrderStatusCode and ProviderRole are now StrEnum instead of (str, Enum)
 - All types using `Result[A, Exception]` have been replace with the equivalent type `ResultE[A]`
+- Order and OrderCollection extend _GeoJsonBase instead of Feature and FeatureCollection, to allow for tighter
+  constraints on fields
 
 ### Deprecated
 
@@ -75,8 +106,6 @@ none
 - Order field `id` must be a string, instead of previously allowing int. This is because while an
   order ID may an integral numeric value, it is not a "number" in the sense that math will be performed
   order ID values, so string represents this better.
-- Order and OrderCollection extend _GeoJsonBase instead of Feature and FeatureCollection, to allow for tighter
-  constraints on fields
 
 ### Deprecated
 

src/stapi_fastapi/backends/product_backend.py

@@ -6,7 +6,7 @@
 from returns.result import ResultE
 
 from stapi_fastapi.models.opportunity import Opportunity, OpportunityRequest
-from stapi_fastapi.models.order import Order, OrderRequest
+from stapi_fastapi.models.order import Order, OrderPayload
 from stapi_fastapi.routers.product_router import ProductRouter
 
 
@@ -27,7 +27,7 @@ async def search_opportunities(
     async def create_order(
         self,
         product_router: ProductRouter,
-        search: OrderRequest,
+        search: OrderPayload,
         request: Request,
     ) -> ResultE[Order]:
         """

src/stapi_fastapi/backends/root_backend.py

@@ -4,7 +4,12 @@
 from returns.maybe import Maybe
 from returns.result import ResultE
 
-from stapi_fastapi.models.order import Order, OrderCollection
+from stapi_fastapi.models.order import (
+    Order,
+    OrderCollection,
+    OrderStatus,
+    OrderStatusPayload,
+)
 
 
 class RootBackend(Protocol):  # pragma: nocover
@@ -21,9 +26,38 @@ async def get_order(self, order_id: str, request: Request) -> ResultE[Maybe[Orde
         Should return returns.results.Success[Order] if order is found.
 
         Should return returns.results.Failure[returns.maybe.Nothing] if the order is
-        not found or if access is denied. If there is an Exception associated with attempting to find the order,
-        then resturns.results.Failure[returns.maybe.Some[Exception]] should be returned.
+        not found or if access is denied.
 
-        Typically, a Failure[Nothing] will result in a 404 and Failure[Some[Exception]] will resulting in a 500.
+        A Failure[Exception] will result in a 500.
+        """
+        ...
+
+    async def get_order_statuses(
+        self, order_id: str, request: Request
+    ) -> ResultE[list[OrderStatus]]:
+        """
+        Get statuses for order with `order_id`.
+
+        Should return returns.results.Success[list[OrderStatus]] if order is found.
+
+        Should return returns.results.Failure[Exception] if the order is
+        not found or if access is denied.
+
+        A Failure[Exception] will result in a 500.
+        """
+        ...
+
+    async def set_order_status(
+        self, order_id: str, payload: OrderStatusPayload, request: Request
+    ) -> ResultE[bool]:
+        """
+        Get statuses for order with `order_id`.
+
+        Should return returns.results.Success[list[OrderStatus]] if order is found.
+
+        Should return returns.results.Failure[Exception] if the order is
+        not found or if access is denied.
+
+        A Failure[Exception] will result in a 500.
         """
         ...

src/stapi_fastapi/models/order.py

@@ -29,17 +29,6 @@ class OrderParameters(BaseModel):
 ORP = TypeVar("ORP", bound=OrderParameters)
 
 
-class OrderRequest(BaseModel, Generic[ORP]):
-    datetime: DatetimeInterval
-    geometry: Geometry
-    # TODO: validate the CQL2 filter?
-    filter: CQL2Filter | None = None
-
-    order_parameters: ORP
-
-    model_config = ConfigDict(strict=True)
-
-
 class OrderStatusCode(StrEnum):
     received = "received"
     accepted = "accepted"
@@ -56,6 +45,11 @@ class OrderStatus(BaseModel):
     links: list[Link] = Field(default_factory=list)
 
 
+class OrderStatuses(BaseModel):
+    statuses: list[OrderStatus]
+    links: list[Link] = Field(default_factory=list)
+
+
 class OrderSearchParameters(BaseModel):
     datetime: DatetimeInterval
     geometry: Geometry
@@ -115,3 +109,22 @@ def __len__(self) -> int:
     def __getitem__(self, index: int) -> Order:
         """get feature at a given index"""
         return self.features[index]
+
+
+class OrderPayload(BaseModel, Generic[ORP]):
+    datetime: DatetimeInterval
+    geometry: Geometry
+    # TODO: validate the CQL2 filter?
+    filter: CQL2Filter | None = None
+
+    order_parameters: ORP
+
+    model_config = ConfigDict(strict=True)
+
+
+class OrderStatusPayload(BaseModel):
+    status_code: OrderStatusCode
+    reason_code: Optional[str] = None
+    reason_text: Optional[str] = None
+
+    model_config = ConfigDict(strict=True)

src/stapi_fastapi/routers/product_router.py

@@ -13,7 +13,7 @@
     OpportunityCollection,
     OpportunityRequest,
 )
-from stapi_fastapi.models.order import Order, OrderRequest
+from stapi_fastapi.models.order import Order, OrderPayload
 from stapi_fastapi.models.product import Product
 from stapi_fastapi.models.shared import Link
 from stapi_fastapi.responses import GeoJSONResponse
@@ -85,13 +85,13 @@ def __init__(
         # the annotation on every `ProductRouter` instance's `create_order`, not just
         # this one's.
         async def _create_order(
-            payload: OrderRequest,
+            payload: OrderPayload,
             request: Request,
             response: Response,
         ) -> Order:
             return await self.create_order(payload, request, response)
 
-        _create_order.__annotations__["payload"] = OrderRequest[
+        _create_order.__annotations__["payload"] = OrderPayload[
             self.product.order_parameters  # type: ignore
         ]
 
@@ -203,7 +203,7 @@ def get_product_order_parameters(self: Self) -> JsonSchemaModel:
         return self.product.order_parameters
 
     async def create_order(
-        self, payload: OrderRequest, request: Request, response: Response
+        self, payload: OrderPayload, request: Request, response: Response
     ) -> Order:
         """
         Create a new order.

src/stapi_fastapi/routers/root_router.py

@@ -3,14 +3,20 @@
 
 from fastapi import APIRouter, HTTPException, Request, status
 from fastapi.datastructures import URL
+from fastapi.responses import Response
 from returns.maybe import Maybe, Some
 from returns.result import Failure, Success
 
 from stapi_fastapi.backends.root_backend import RootBackend
 from stapi_fastapi.constants import TYPE_GEOJSON, TYPE_JSON
 from stapi_fastapi.exceptions import NotFoundException
 from stapi_fastapi.models.conformance import CORE, Conformance
-from stapi_fastapi.models.order import Order, OrderCollection
+from stapi_fastapi.models.order import (
+    Order,
+    OrderCollection,
+    OrderStatuses,
+    OrderStatusPayload,
+)
 from stapi_fastapi.models.product import Product, ProductsCollection
 from stapi_fastapi.models.root import RootResponse
 from stapi_fastapi.models.shared import Link
@@ -84,6 +90,22 @@ def __init__(
             tags=["Orders"],
         )
 
+        self.add_api_route(
+            "/orders/{order_id}/statuses",
+            self.get_order_statuses,
+            methods=["GET"],
+            name=f"{self.name}:list-order-statuses",
+            tags=["Orders"],
+        )
+
+        self.add_api_route(
+            "/orders/{order_id}/statuses",
+            self.set_order_status,
+            methods=["POST"],
+            name=f"{self.name}:set-order-status",
+            tags=["Orders"],
+        )
+
     def get_root(self, request: Request) -> RootResponse:
         return RootResponse(
             id="STAPI API",
@@ -168,8 +190,20 @@ async def get_order(self: Self, order_id: str, request: Request) -> Order:
         """
         match await self.backend.get_order(order_id, request):
             case Success(Some(order)):
-                order.links.append(
-                    Link(href=str(request.url), rel="self", type=TYPE_GEOJSON)
+                order.links.extend(
+                    [
+                        Link(href=str(request.url), rel="self", type=TYPE_GEOJSON),
+                        Link(
+                            href=str(
+                                request.url_for(
+                                    f"{self.name}:list-order-statuses",
+                                    order_id=order_id,
+                                )
+                            ),
+                            rel="monitor",
+                            type=TYPE_JSON,
+                        ),
+                    ]
                 )
                 return order
             case Success(Maybe.empty):
@@ -185,6 +219,52 @@ async def get_order(self: Self, order_id: str, request: Request) -> Order:
             case _:
                 raise AssertionError("Expected code to be unreachable")
 
+    async def get_order_statuses(
+        self: Self, order_id: str, request: Request
+    ) -> OrderStatuses:
+        match await self.backend.get_order_statuses(order_id, request):
+            case Success(statuses):
+                return OrderStatuses(
+                    statuses=statuses,
+                    links=[
+                        Link(
+                            href=str(
+                                request.url_for(
+                                    f"{self.name}:list-order-statuses",
+                                    order_id=order_id,
+                                )
+                            ),
+                            rel="self",
+                            type=TYPE_JSON,
+                        )
+                    ],
+                )
+            case Failure(e):
+                logging.exception(
+                    "An error occurred while retrieving order statuses", e
+                )
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Error finding Order Statuses",
+                )
+            case _:
+                raise AssertionError("Expected code to be unreachable")
+
+    async def set_order_status(
+        self: Self, order_id: str, payload: OrderStatusPayload, request: Request
+    ) -> Response:
+        match await self.backend.set_order_status(order_id, payload, request):
+            case Success(_):
+                return Response(status_code=status.HTTP_202_ACCEPTED)
+            case Failure(e):
+                logging.exception("An error occurred while setting order status", e)
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Error setting Order Status",
+                )
+            case _:
+                raise AssertionError("Expected code to be unreachable")
+
     def add_product(self: Self, product: Product) -> None:
         # Give the include a prefix from the product router
         product_router = ProductRouter(product, self)