Add an API prefix

It's now possible to configure an API prefix, which affects all LabThings-generated URLs.

I've also switched a couple of places from passing the app around to creating an APIRouter, which feels much cleaner.

So far, tests pass but I've not tried to set a prefix.

Author: rwb27

src/labthings_fastapi/actions.py

@@ -36,7 +36,7 @@
 )
 from weakref import WeakSet
 import weakref
-from fastapi import FastAPI, HTTPException, Request, Body, BackgroundTasks
+from fastapi import APIRouter, FastAPI, HTTPException, Request, Body, BackgroundTasks
 from pydantic import BaseModel, create_model
 
 from .middleware.url_for import URLFor
@@ -71,7 +71,7 @@
     from .thing import Thing
 
 
-__all__ = ["ACTION_INVOCATIONS_PATH", "Invocation", "ActionManager"]
+__all__ = ["Invocation", "ActionManager"]
 
 
 ACTION_INVOCATIONS_PATH = "/action_invocations"
@@ -438,17 +438,18 @@ def expire_invocations(self) -> None:
             for k in to_delete:
                 del self._invocations[k]
 
-    def attach_to_app(self, app: FastAPI) -> None:
-        """Add /action_invocations and /action_invocation/{id} endpoints to FastAPI.
+    def router(self) -> APIRouter:
+        """Create a FastAPI Router with action-related endpoints.
 
-        :param app: The `fastapi.FastAPI` application to which we add the endpoints.
+        :return: a Router with all action-related endpoints.
         """
+        router = APIRouter()
 
-        @app.get(ACTION_INVOCATIONS_PATH, response_model=list[InvocationModel])
+        @router.get(ACTION_INVOCATIONS_PATH, response_model=list[InvocationModel])
         def list_all_invocations(request: Request) -> list[InvocationModel]:
             return self.list_invocations(request=request)
 
-        @app.get(
+        @router.get(
             ACTION_INVOCATIONS_PATH + "/{id}",
             responses={404: {"description": "Invocation ID not found"}},
         )
@@ -473,7 +474,7 @@ def action_invocation(id: uuid.UUID, request: Request) -> InvocationModel:
                     detail="No action invocation found with ID {id}",
                 ) from e
 
-        @app.get(
+        @router.get(
             ACTION_INVOCATIONS_PATH + "/{id}/output",
             response_model=Any,
             responses={
@@ -521,7 +522,7 @@ def action_invocation_output(id: uuid.UUID) -> Any:
                     return invocation.output.response()
                 return invocation.output
 
-        @app.delete(
+        @router.delete(
             ACTION_INVOCATIONS_PATH + "/{id}",
             response_model=None,
             responses={
@@ -561,6 +562,8 @@ def delete_invocation(id: uuid.UUID) -> None:
                     )
                 invocation.cancel()
 
+        return router
+
 
 ACTION_POST_NOTICE = """
 ## Important note

src/labthings_fastapi/server/__init__.py

@@ -12,7 +12,7 @@
 import os
 import logging
 
-from fastapi import FastAPI, Request
+from fastapi import APIRouter, FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from anyio.from_thread import BlockingPortal
 from contextlib import asynccontextmanager, AsyncExitStack
@@ -65,6 +65,7 @@ def __init__(
         self,
         things: ThingsConfig,
         settings_folder: Optional[str] = None,
+        api_prefix: str = "",
         application_config: Optional[Mapping[str, Any]] = None,
         debug: bool = False,
     ) -> None:
@@ -83,8 +84,9 @@ def __init__(
             arguments, and any connections to other `.Thing`\ s.
         :param settings_folder: the location on disk where `.Thing`
             settings will be saved.
+        :param api_prefix: An optional prefix for all API routes. This must either
+            be empty, or start with a slash and not end with a slash.
         :param application_config: A mapping containing custom configuration for the
-            application. This is not processed by LabThings. Each `.Thing` can access
             application. This is not processed by LabThings. Each `.Thing` can access
             this via the Thing-Server interface.
         :param debug: If ``True``, set the log level for `.Thing` instances to
@@ -103,9 +105,9 @@ def __init__(
         self._set_url_for_middleware()
         self.settings_folder = settings_folder or "./settings"
         self.action_manager = ActionManager()
-        self.action_manager.attach_to_app(self.app)
-        self.app.include_router(blob.router)  # include blob download endpoint
-        self._add_things_view_to_app()
+        self.app.include_router(self.action_manager.router(), prefix=self._api_prefix)
+        self.app.include_router(blob.router, prefix=self._api_prefix)
+        self.app.include_router(self._things_view_router(), prefix=self._api_prefix)
         self.blocking_portal: Optional[BlockingPortal] = None
         self.startup_status: dict[str, str | dict] = {"things": {}}
         global _thing_servers  # noqa: F824
@@ -171,6 +173,15 @@ def application_config(self) -> Mapping[str, Any] | None:
         """
         return self._config.application_config
 
+    @property
+    def _api_prefix(self) -> str:
+        """A string that prefixes all URLs in the application.
+
+        This must either be empty, or start with a slash and not
+        end with a slash.
+        """
+        return self._config.api_prefix
+
     ThingInstance = TypeVar("ThingInstance", bound=Thing)
 
     def things_by_class(self, cls: type[ThingInstance]) -> Sequence[ThingInstance]:
@@ -214,7 +225,7 @@ def path_for_thing(self, name: str) -> str:
         """
         if name not in self._things:
             raise KeyError(f"No thing named {name} has been added to this server.")
-        return f"/{name}/"
+        return f"{self._api_prefix}/{name}/"
 
     def _create_things(self) -> Mapping[str, Thing]:
         r"""Create the Things, add them to the server, and connect them up if needed.
@@ -322,15 +333,14 @@ async def lifespan(self, app: FastAPI) -> AsyncGenerator[None, None]:
 
         self.blocking_portal = None
 
-    def _add_things_view_to_app(self) -> None:
-        """Add an endpoint that shows the list of attached things."""
+    def _things_view_router(self) -> APIRouter:
+        """Create a router for the endpoint that shows the list of attached things.
+
+        :returns: an APIRouter with the `thing_descriptions` endpoint.
+        """
+        router = APIRouter()
         thing_server = self
 
-        @self.app.get(
-            "/thing_descriptions/",
-            response_model_exclude_none=True,
-            response_model_by_alias=True,
-        )
         def thing_descriptions(request: Request) -> Mapping[str, ThingDescription]:
             """Describe all the things available from this server.
 
@@ -351,6 +361,15 @@ def thing_descriptions(request: Request) -> Mapping[str, ThingDescription]:
                 for name, thing in thing_server.things.items()
             }
 
+        router.add_api_route(
+            "/thing_descriptions/",
+            thing_descriptions,
+            response_model_exclude_none=True,
+            response_model_by_alias=True,
+        )
+
+        return router
+
         @self.app.get("/things/")
         def thing_paths(request: Request) -> Mapping[str, str]:
             """URLs pointing to the Thing Descriptions of each Thing.

src/labthings_fastapi/server/config_model.py

@@ -180,6 +180,30 @@ def thing_configs(self) -> Mapping[ThingName, ThingConfig]:
         description="The location of the settings folder.",
     )
 
+    api_prefix: str = Field(
+        default="",
+        pattern="(\/[\w-]+)*",
+        description=(
+            """A prefix added to all endpoints, including Things.
+
+            The prefix must either be empty, or start with a forward
+            slash, but not end with one. This is enforced by a regex validator
+            on this field.
+
+            By default, LabThings creates a few LabThings-specific endpoints
+            (`/action_invocations/` and `/blob/` for example) as well as
+            endpoints for attributes of `Thing`s. This prefix will apply to
+            all of those endpoints.
+
+            For example, if `api_prefix` is set to `/api/v1` then a `Thing`
+            called `my_thing` might appear at `/api/v1/my_thing/` and the
+            blob download URL would be `/api/v1/blob/{id}`.
+
+            Leading and trailing slashes will be normalised.
+            """
+        ),
+    )
+
     application_config: dict[str, Any] | None = Field(
         default=None,
         description=(