Add Conformance endpoints (#101)

* update ruff to v0.7.3 and format code with it

* enable mypy, and fix code warnings produced by it

* run lint with python 3.12

* add conformance endpoints

* remove init method from Conformance

* refactor use of assert_link

---------

Co-authored-by: Phil Varner <[email protected]>

Author: philvarner

CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+- Conformance endpoint `/conformance` and root body `conformsTo` attribute.
+
+### Changed
+
+none
+
+### Deprecated
+
+none
+
+### Removed
+
+none
+
+### Fixed
+
+none
+
+### Security
+
+none
+
 ## [v0.1.0] - 2024-10-23
 
 Initial release

bin/server.py

@@ -5,6 +5,7 @@
 from stapi_fastapi.backends.product_backend import ProductBackend
 from stapi_fastapi.backends.root_backend import RootBackend
 from stapi_fastapi.exceptions import ConstraintsException, NotFoundException
+from stapi_fastapi.models.conformance import CORE
 from stapi_fastapi.models.opportunity import (
     Opportunity,
     OpportunityPropertiesBase,
@@ -104,7 +105,7 @@ class TestSpotlightProperties(OpportunityPropertiesBase):
     backend=product_backend,
 )
 
-root_router = RootRouter(root_backend)
+root_router = RootRouter(root_backend, conformances=[CORE])
 root_router.add_product(product)
 app: FastAPI = FastAPI()
 app.include_router(root_router, prefix="")

src/stapi_fastapi/models/conformance.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, Field
+
+CORE = "https://stapi.example.com/v0.1.0/core"
+OPPORTUNITIES = "https://stapi.example.com/v0.1.0/opportunities"
+
+
+class Conformance(BaseModel):
+    conforms_to: list[str] = Field(
+        default_factory=list, serialization_alias="conformsTo"
+    )

src/stapi_fastapi/models/root.py

@@ -1,7 +1,11 @@
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from stapi_fastapi.models.shared import Link
 
 
 class RootResponse(BaseModel):
-    links: list[Link]
+    id: str
+    conformsTo: list[str] = Field(default_factory=list)
+    title: str = ""
+    description: str = ""
+    links: list[Link] = Field(default_factory=list)

src/stapi_fastapi/routers/root_router.py

@@ -5,6 +5,7 @@
 
 from stapi_fastapi.backends.root_backend import RootBackend
 from stapi_fastapi.constants import TYPE_GEOJSON, TYPE_JSON
+from stapi_fastapi.models.conformance import CORE, Conformance
 from stapi_fastapi.models.order import Order, OrderCollection
 from stapi_fastapi.models.product import Product, ProductsCollection
 from stapi_fastapi.models.root import RootResponse
@@ -17,15 +18,17 @@ class RootRouter(APIRouter):
     def __init__(
         self,
         backend: RootBackend,
+        conformances: list[str] = [CORE],
         name: str = "root",
-        openapi_endpoint_name="openapi",
-        docs_endpoint_name="swagger_ui_html",
+        openapi_endpoint_name: str = "openapi",
+        docs_endpoint_name: str = "swagger_ui_html",
         *args,
         **kwargs,
     ) -> None:
         super().__init__(*args, **kwargs)
         self.backend = backend
         self.name = name
+        self.conformances = conformances
         self.openapi_endpoint_name = openapi_endpoint_name
         self.docs_endpoint_name = docs_endpoint_name
 
@@ -43,6 +46,14 @@ def __init__(
             tags=["Root"],
         )
 
+        self.add_api_route(
+            "/conformance",
+            self.get_conformance,
+            methods=["GET"],
+            name=f"{self.name}:conformance",
+            tags=["Conformance"],
+        )
+
         self.add_api_route(
             "/products",
             self.get_products,
@@ -71,12 +82,19 @@ def __init__(
 
     def get_root(self, request: Request) -> RootResponse:
         return RootResponse(
+            id="STAPI API",
+            conformsTo=self.conformances,
             links=[
                 Link(
                     href=str(request.url_for(f"{self.name}:root")),
                     rel="self",
                     type=TYPE_JSON,
                 ),
+                Link(
+                    href=str(request.url_for(f"{self.name}:conformance")),
+                    rel="conformance",
+                    type=TYPE_JSON,
+                ),
                 Link(
                     href=str(request.url_for(f"{self.name}:list-products")),
                     rel="products",
@@ -97,9 +115,12 @@ def get_root(self, request: Request) -> RootResponse:
                     rel="service-docs",
                     type="text/html",
                 ),
-            ]
+            ],
         )
 
+    def get_conformance(self, request: Request) -> Conformance:
+        return Conformance(conforms_to=self.conformances)
+
     def get_products(self, request: Request) -> ProductsCollection:
         return ProductsCollection(
             products=[pr.get_product(request) for pr in self.product_routers.values()],

tests/conformance_test.py

@@ -0,0 +1,15 @@
+from fastapi import status
+from fastapi.testclient import TestClient
+
+from stapi_fastapi.models.conformance import CORE
+
+
+def test_conformance(stapi_client: TestClient) -> None:
+    res = stapi_client.get("/conformance")
+
+    assert res.status_code == status.HTTP_200_OK
+    assert res.headers["Content-Type"] == "application/json"
+
+    body = res.json()
+
+    assert body["conformsTo"] == [CORE]

tests/conftest.py

@@ -1,6 +1,6 @@
 from collections.abc import Iterator
 from datetime import UTC, datetime, timedelta, timezone
-from typing import Callable
+from typing import Any, Callable
 from urllib.parse import urljoin
 from uuid import uuid4
 
@@ -19,6 +19,7 @@
 from stapi_fastapi.routers.root_router import RootRouter
 
 from .backends import MockOrderDB, MockProductBackend, MockRootBackend
+from .utils import find_link
 
 
 class TestSpotlightProperties(OpportunityPropertiesBase):
@@ -87,6 +88,23 @@ def url_for(value: str) -> str:
     yield url_for
 
 
+@pytest.fixture
+def assert_link(url_for) -> Callable:
+    def _assert_link(
+        req: str,
+        body: dict[str, Any],
+        rel: str,
+        path: str,
+        media_type: str = "application/json",
+    ):
+        link = find_link(body["links"], rel)
+        assert link, f"{req} Link[rel={rel}] should exist"
+        assert link["type"] == media_type
+        assert link["href"] == url_for(path)
+
+    return _assert_link
+
+
 @pytest.fixture
 def products(mock_product_test_spotlight: Product) -> list[Product]:
     return [mock_product_test_spotlight]

tests/root_test.py

@@ -1,28 +1,22 @@
 from fastapi import status
 from fastapi.testclient import TestClient
 
-from .utils import find_link
+from stapi_fastapi.models.conformance import CORE
 
 
-def test_root(stapi_client: TestClient, url_for) -> None:
+def test_root(stapi_client: TestClient, assert_link) -> None:
     res = stapi_client.get("/")
 
     assert res.status_code == status.HTTP_200_OK
     assert res.headers["Content-Type"] == "application/json"
 
-    data = res.json()
+    body = res.json()
 
-    link = find_link(data["links"], "self")
-    assert link, "GET / Link[rel=self] should exist"
-    assert link["type"] == "application/json"
-    assert link["href"] == url_for("/")
+    assert body["conformsTo"] == [CORE]
 
-    link = find_link(data["links"], "service-description")
-    assert link, "GET / Link[rel=service-description] should exist"
-    assert link["type"] == "application/json"
-    assert str(link["href"]) == url_for("/openapi.json")
-
-    link = find_link(data["links"], "service-docs")
-    assert link, "GET / Link[rel=service-docs] should exist"
-    assert link["type"] == "text/html"
-    assert str(link["href"]) == url_for("/docs")
+    assert_link("GET /", body, "self", "/")
+    assert_link("GET /", body, "service-description", "/openapi.json")
+    assert_link("GET /", body, "service-docs", "/docs", media_type="text/html")
+    assert_link("GET /", body, "conformance", "/conformance")
+    assert_link("GET /", body, "products", "/products")
+    assert_link("GET /", body, "orders", "/orders")

tests/utils.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-link_dict = dict[str, Any]
+type link_dict = dict[str, Any]
 
 
 def find_link(links: list[link_dict], rel: str) -> link_dict | None: