✨ Refactor changelog handling in API routes and add tests for route configuration

Author: pcrespov

services/api-server/src/simcore_service_api_server/api/routes/_constants.py

@@ -1,4 +1,4 @@
-from typing import Final
+from typing import Any, Final
 
 #
 # CHANGELOG formatted-messages for API routes
@@ -9,19 +9,16 @@
 # - Inspired on this idea https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions
 #
 
-# new routes
+# newly created endpoint in given version
 FMSG_CHANGELOG_NEW_IN_VERSION: Final[str] = "New in *version {}*\n"
 
-# new inputs/outputs in routes
-FMSG_CHANGELOG_ADDED_IN_VERSION: Final[str] = "Added in *version {}*: {}\n"
-
-# changes on inputs/outputs in routes
+# changes in given version with message
 FMSG_CHANGELOG_CHANGED_IN_VERSION: Final[str] = "Changed in *version {}*: {}\n"
 
-# removed on inputs/outputs in routes
-FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT: Final[str] = "Removed in *version {}*: {}\n"
+# marked as deprecated and will be removed in given version
+FMSG_CHANGELOG_REMOVED_IN_VERSION: Final[str] = "Removed in *version {}*: {}\n"
 
-FMSG_DEPRECATED_ROUTE_NOTICE: Final[str] = (
+FMSG_CHANGELOG_DEPRECATED: Final[str] = (
     "🚨 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\n"
     "Please use `{}` instead.\n\n"
 )
@@ -33,8 +30,8 @@ def create_route_description(
     *,
     base: str = "",
     deprecated: bool = False,
-    alternative: str | None = None,  # alternative
-    changelog: list[str] | None = None
+    alternative: str | None = None,  # alternative route to use
+    changelog: list[str] | None = None,
 ) -> str:
     """
     Builds a consistent route description with optional deprecation and changelog information.
@@ -51,7 +48,7 @@ def create_route_description(
 
     if deprecated:
         assert alternative, "If deprecated, alternative must be provided"  # nosec
-        parts.append(FMSG_DEPRECATED_ROUTE_NOTICE.format(alternative))
+        parts.append(FMSG_CHANGELOG_DEPRECATED.format(alternative))
 
     if base:
         parts.append(base)
@@ -60,3 +57,68 @@ def create_route_description(
         parts.append("\n".join(changelog))
 
     return "\n\n".join(parts)
+
+
+def create_route_config(
+    base_description: str = "",
+    *,
+    to_be_released_in: str | None = None,
+    to_be_removed_in: str | None = None,
+    alternative: str | None = None,
+    changelog: list[str] | None = None,
+) -> dict[str, Any]:
+    """
+    Creates route configuration options including description.
+
+    Args:
+        base_description: Main route description
+        to_be_released_in: Version where this route will be released (for upcoming features)
+        to_be_removed_in: Version where this route will be removed (for deprecated endpoints)
+        alternative: Alternative route to use (required if to_be_removed_in is provided)
+        changelog: List of formatted changelog strings
+
+    Returns:
+        dict: Route configuration options that can be used as kwargs for route decorators
+    """
+    route_options: dict[str, Any] = {}
+
+    # Build changelog
+    if changelog is None:
+        changelog = []
+
+    if to_be_released_in:
+        # Add version information to the changelog if not already there
+        version_note = FMSG_CHANGELOG_NEW_IN_VERSION.format(to_be_released_in)
+        if not any(version_note in item for item in changelog):
+            changelog.append(version_note)
+        # Hide from schema until released
+        route_options["include_in_schema"] = False
+
+    if to_be_removed_in:
+        # Require an alternative route if this endpoint will be removed
+        assert (  # nosec
+            alternative
+        ), "If to_be_removed_in is provided, alternative must be provided"  # nosec
+
+        # Add removal notice to the changelog if not already there
+        removal_message = (
+            "This endpoint is deprecated and will be removed in a future version"
+        )
+        removal_note = FMSG_CHANGELOG_REMOVED_IN_VERSION.format(
+            to_be_removed_in, removal_message
+        )
+        if not any(removal_note in item for item in changelog):
+            changelog.append(removal_note)
+
+        # Mark as deprecated
+        route_options["deprecated"] = True
+
+    # Create description
+    route_options["description"] = create_route_description(
+        base=base_description,
+        deprecated=bool(to_be_removed_in),
+        alternative=alternative,
+        changelog=changelog,
+    )
+
+    return route_options

services/api-server/src/simcore_service_api_server/api/routes/files.py

@@ -30,9 +30,8 @@
 )
 from simcore_sdk.node_ports_common.filemanager import upload_path as storage_upload_path
 from simcore_service_api_server.api.routes._constants import (
-    FMSG_CHANGELOG_ADDED_IN_VERSION,
-    FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT,
-    create_route_description,
+    FMSG_CHANGELOG_NEW_IN_VERSION,
+    create_route_config,
 )
 from starlette.datastructures import URL
 from starlette.responses import RedirectResponse
@@ -141,16 +140,12 @@ async def _create_domain_file(
     "",
     response_model=list[OutputFile],
     responses=_FILE_STATUS_CODES,
-    description=create_route_description(
-        base="Lists all files stored in the system",
-        deprecated=True,
+    **create_route_config(
+        base_description="Lists all files stored in the system",
+        to_be_removed_in="0.7",
         alternative="GET /v0/files/page",
         changelog=[
-            FMSG_CHANGELOG_ADDED_IN_VERSION.format("0.5", ""),
-            FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT.format(
-                "0.7",
-                "This endpoint is deprecated and will be removed in a future version",
-            ),
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
         ],
     ),
 )

services/api-server/src/simcore_service_api_server/api/routes/programs.py

@@ -23,8 +23,7 @@
 from ..._service_programs import ProgramService
 from ...api.routes._constants import (
     DEFAULT_MAX_STRING_LENGTH,
-    FMSG_CHANGELOG_NEW_IN_VERSION,
-    create_route_description,
+    create_route_config,
 )
 from ...models.basic_types import VersionStr
 from ...models.pagination import Page, PaginationParams
@@ -39,13 +38,10 @@
 @router.get(
     "",
     response_model=Page[Program],
-    description=create_route_description(
-        base="Lists the latest of all available programs",
-        changelog=[
-            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.8"),
-        ],
+    **create_route_config(
+        base_description="Lists the latest of all available programs",
+        to_be_released_in="0.8",
     ),
-    include_in_schema=False,  # TO BE RELEASED in 0.8
 )
 async def list_programs(
     user_id: Annotated[PositiveInt, Depends(get_current_user_id)],
@@ -78,13 +74,10 @@ async def list_programs(
 @router.get(
     "/{program_key:path}/releases",
     response_model=Page[Program],
-    description=create_route_description(
-        base="Lists the latest of all available programs",
-        changelog=[
-            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.8"),
-        ],
+    **create_route_config(
+        base_description="Lists the latest of all available programs",
+        to_be_released_in="0.8",
     ),
-    include_in_schema=False,  # TO BE RELEASED in 0.8
 )
 async def list_program_history(
     program_key: ProgramKeyId,

services/api-server/src/simcore_service_api_server/api/routes/solvers.py

@@ -26,7 +26,8 @@
 from ..dependencies.webserver_http import AuthSession, get_webserver_session
 from ._constants import (
     FMSG_CHANGELOG_NEW_IN_VERSION,
-    FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT,
+    FMSG_CHANGELOG_REMOVED_IN_VERSION,
+    create_route_config,
     create_route_description,
 )
 
@@ -59,13 +60,13 @@
     "",
     response_model=list[Solver],
     responses=_SOLVER_STATUS_CODES,
-    description=create_route_description(
-        base="Lists all available solvers (latest version)",
-        deprecated=True,
+    **create_route_config(
+        base_description="Lists all available solvers (latest version)",
+        to_be_removed_in="0.7",
         alternative="GET /v0/solvers/page",
         changelog=[
             FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0", ""),
-            FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT.format(
+            FMSG_CHANGELOG_REMOVED_IN_VERSION.format(
                 "0.7",
                 "This endpoint is deprecated and will be removed in a future version",
             ),
@@ -141,7 +142,7 @@ async def get_solvers_page(
         alternative="GET /v0/solvers/{solver_key}/releases/page",
         changelog=[
             FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0", ""),
-            FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT.format(
+            FMSG_CHANGELOG_REMOVED_IN_VERSION.format(
                 "0.7",
                 "This endpoint is deprecated and will be removed in a future version",
             ),

services/api-server/src/simcore_service_api_server/api/routes/solvers_jobs.py

@@ -37,7 +37,6 @@
 from ..dependencies.services import get_api_client, get_solver_service
 from ..dependencies.webserver_http import AuthSession, get_webserver_session
 from ._constants import (
-    FMSG_CHANGELOG_ADDED_IN_VERSION,
     FMSG_CHANGELOG_CHANGED_IN_VERSION,
     FMSG_CHANGELOG_NEW_IN_VERSION,
 )
@@ -164,8 +163,10 @@ async def delete_job(
         },
     },
     description="Starts job job_id created with the solver solver_key:version\n\n"
-    + FMSG_CHANGELOG_ADDED_IN_VERSION.format("0.4.3", "query parameter `cluster_id`")
-    + FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+    + FMSG_CHANGELOG_CHANGED_IN_VERSION.format(
+        "0.4.3", "adds query parameter `cluster_id`"
+    )
+    + FMSG_CHANGELOG_CHANGED_IN_VERSION.format(
         "0.6", "responds with a 202 when successfully starting a computation"
     )
     + FMSG_CHANGELOG_CHANGED_IN_VERSION.format(

services/api-server/src/simcore_service_api_server/api/routes/solvers_jobs_getters.py

@@ -59,7 +59,8 @@
 from ..dependencies.webserver_http import AuthSession, get_webserver_session
 from ._constants import (
     FMSG_CHANGELOG_NEW_IN_VERSION,
-    FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT,
+    FMSG_CHANGELOG_REMOVED_IN_VERSION,
+    create_route_config,
     create_route_description,
 )
 from .solvers_jobs import (
@@ -192,13 +193,13 @@ async def list_all_solvers_jobs(
     "/{solver_key:path}/releases/{version}/jobs",
     response_model=list[Job],
     responses=JOBS_STATUS_CODES,
-    description=create_route_description(
-        base="List of jobs in a specific released solver",
+    **create_route_config(
+        base_description="List of jobs in a specific released solver (limited to 20 jobs)",
         deprecated=True,
         alternative="GET /{solver_key}/releases/{version}/jobs/page",
         changelog=[
             FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
-            FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT.format(
+            FMSG_CHANGELOG_REMOVED_IN_VERSION.format(
                 "0.7",
                 "This endpoint is deprecated and will be removed in a future version",
             ),