✨ public-api 0.7.1: adds version_display field in the Solver response model (#7694)

pcrespov · web-flow · commit e888734d1eb6 · 2025-05-17T09:26:25.000Z
diff --git a/services/api-server/VERSION b/services/api-server/VERSION
@@ -1 +1 @@
-0.7.0
+0.7.1
diff --git a/services/api-server/openapi.json b/services/api-server/openapi.json
@@ -3,7 +3,7 @@
   "info": {
     "title": "osparc.io public API",
     "description": "osparc-simcore public API specifications",
-    "version": "0.7.0"
+    "version": "0.7.1"
   },
   "paths": {
     "/v0/meta": {
@@ -1423,7 +1423,7 @@
           "solvers"
         ],
         "summary": "List Solvers",
-        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/page` instead.\n\n\n\nLists all available solvers (latest version)\n\nNew in *version 0.5.0*\n\nRemoved in *version 0.7*: This endpoint is deprecated and will be removed in a future version",
+        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/page` instead.\n\n\n\nLists all available solvers (latest version)\n\nNew in *version 0.5.0*",
         "operationId": "list_solvers",
         "responses": {
           "200": {
@@ -1514,7 +1514,7 @@
           "solvers"
         ],
         "summary": "Lists All Releases",
-        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/{solver_key}/releases/page` instead.\n\n\n\nLists all released solvers (not just latest version)\n\nNew in *version 0.5.0*\n\nRemoved in *version 0.7*: This endpoint is deprecated and will be removed in a future version",
+        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/{solver_key}/releases/page` instead.\n\n\n\nLists all released solvers (not just latest version)\n\nNew in *version 0.5.0*",
         "operationId": "list_solvers_releases",
         "responses": {
           "200": {
@@ -1604,8 +1604,8 @@
         "tags": [
           "solvers"
         ],
-        "summary": "Get Latest Release of a Solver",
-        "description": "Gets latest release of a solver",
+        "summary": "Get Solver",
+        "description": "Gets latest release of a solver\n\nAdded in *version 0.7.1*: `version_display` field in the response",
         "operationId": "get_solver",
         "security": [
           {
@@ -1714,7 +1714,7 @@
           "solvers"
         ],
         "summary": "List Solver Releases",
-        "description": "Lists all releases of a given (one) solver\n\nSEE get_solver_releases_page for a paginated version of this function",
+        "description": "Lists all releases of a given (one) solver\n\nAdded in *version 0.7.1*: `version_display` field in the response",
         "operationId": "list_solver_releases",
         "security": [
           {
@@ -1827,7 +1827,7 @@
           "solvers"
         ],
         "summary": "Get Solver Release",
-        "description": "Gets a specific release of a solver",
+        "description": "Gets a specific release of a solver\n\nAdded in *version 0.7.1*: `version_display` field in the response",
         "operationId": "get_solver_release",
         "security": [
           {
@@ -1946,7 +1946,7 @@
           "solvers"
         ],
         "summary": "List Solver Ports",
-        "description": "Lists inputs and outputs of a given solver\n\nNew in *version 0.5.0*",
+        "description": "Lists inputs and outputs of a given solver\n\nNew in *version 0.5.0*\n\nAdded in *version 0.7.1*: `version_display` field in the response",
         "operationId": "list_solver_ports",
         "security": [
           {
@@ -2065,7 +2065,7 @@
           "solvers"
         ],
         "summary": "Get Solver Pricing Plan",
-        "description": "Gets solver pricing plan\n\nNew in *version 0.7*",
+        "description": "Gets solver pricing plan\n\nNew in *version 0.7*\n\nAdded in *version 0.7.1*: `version_display` field in the response",
         "operationId": "get_solver_pricing_plan",
         "security": [
           {
@@ -10465,6 +10465,18 @@
             "type": "string",
             "title": "Maintainer",
             "description": "Maintainer of the solver"
+          },
+          "version_display": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Version Display",
+            "description": "A user-friendly or marketing name for the release."
           }
         },
         "type": "object",
@@ -10483,7 +10495,8 @@
           "maintainer": "info@itis.swiss",
           "title": "iSolve",
           "url": "https://api.osparc.io/v0/solvers/simcore%2Fservices%2Fcomp%2Fisolve/releases/2.1.1",
-          "version": "2.1.1"
+          "version": "2.1.1",
+          "version_display": "2.1.1-2023-10-01"
         }
       },
       "SolverFunction": {
diff --git a/services/api-server/setup.cfg b/services/api-server/setup.cfg
@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.7.0
+current_version = 0.7.1
 commit = True
 message = services/api-server version: {current_version} → {new_version}
 tag = False
diff --git a/services/api-server/src/simcore_service_api_server/api/routes/solvers.py b/services/api-server/src/simcore_service_api_server/api/routes/solvers.py
@@ -25,8 +25,8 @@
 from ..dependencies.services import get_catalog_service, get_solver_service
 from ..dependencies.webserver_http import AuthSession, get_webserver_session
 from ._constants import (
+    FMSG_CHANGELOG_ADDED_IN_VERSION,
     FMSG_CHANGELOG_NEW_IN_VERSION,
-    FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT,
     create_route_description,
 )
 
@@ -56,19 +56,13 @@
         alternative="GET /v0/solvers/page",
         changelog=[
             FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0", ""),
-            FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT.format(
-                "0.7",
-                "This endpoint is deprecated and will be removed in a future version",
-            ),
         ],
     ),
 )
 async def list_solvers(
     catalog_service: Annotated[CatalogService, Depends(get_catalog_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Lists all available solvers (latest version)"""
-
     services, _ = await catalog_service.list_latest_releases(
         filters=ServiceListFilters(service_type=ServiceType.COMPUTATIONAL),
     )
@@ -124,10 +118,6 @@ 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(
-                "0.7",
-                "This endpoint is deprecated and will be removed in a future version",
-            ),
         ],
     ),
 )
@@ -167,21 +157,25 @@ async def list_solvers_releases(
 @router.get(
     "/{solver_key:path}/latest",
     response_model=Solver,
-    summary="Get Latest Release of a Solver",
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Gets latest release of a solver",
+        changelog=[
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def get_solver(
     solver_key: SolverKeyId,
     solver_service: Annotated[SolverService, Depends(get_solver_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Gets latest release of a solver"""
     # IMPORTANT: by adding /latest, we avoid changing the order of this entry in the router list
     # otherwise, {solver_key:path} will override and consume any of the paths that follow.
     try:
-        solver = await solver_service.get_latest_release(
-            solver_key=solver_key,
-        )
+        solver = await solver_service.get_latest_release(solver_key=solver_key)
         solver.url = url_for(
             "get_solver_release", solver_key=solver.id, version=solver.version
         )
@@ -199,16 +193,20 @@ async def get_solver(
     "/{solver_key:path}/releases",
     response_model=list[Solver],
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Lists all releases of a given (one) solver",
+        changelog=[
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def list_solver_releases(
     solver_key: SolverKeyId,
     solver_service: Annotated[SolverService, Depends(get_solver_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Lists all releases of a given (one) solver
-
-    SEE get_solver_releases_page for a paginated version of this function
-    """
     all_releases: list[Solver] = []
     for page_params in iter_pagination_params(limit=DEFAULT_PAGINATION_LIMIT):
         solvers, page_meta = await solver_service.solver_release_history(
@@ -267,14 +265,21 @@ async def get_solver_releases_page(
     "/{solver_key:path}/releases/{version}",
     response_model=Solver,
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Gets a specific release of a solver",
+        changelog=[
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def get_solver_release(
     solver_key: SolverKeyId,
     version: VersionStr,
     solver_service: Annotated[SolverService, Depends(get_solver_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Gets a specific release of a solver"""
     try:
         solver: Solver = await solver_service.get_solver(
             solver_key=solver_key,
@@ -302,8 +307,15 @@ async def get_solver_release(
     "/{solver_key:path}/releases/{version}/ports",
     response_model=OnePage[SolverPort],
     responses=_SOLVER_STATUS_CODES,
-    description="Lists inputs and outputs of a given solver\n\n"
-    + FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0"),
+    description=create_route_description(
+        base="Lists inputs and outputs of a given solver",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0"),
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def list_solver_ports(
     solver_key: SolverKeyId,
@@ -322,9 +334,16 @@ async def list_solver_ports(
 @router.get(
     "/{solver_key:path}/releases/{version}/pricing_plan",
     response_model=ServicePricingPlanGetLegacy,
-    description="Gets solver pricing plan\n\n"
-    + FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Gets solver pricing plan",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def get_solver_pricing_plan(
     solver_key: SolverKeyId,
diff --git a/services/api-server/src/simcore_service_api_server/models/schemas/solvers.py b/services/api-server/src/simcore_service_api_server/models/schemas/solvers.py
@@ -1,4 +1,4 @@
-from typing import Annotated, Any, Literal
+from typing import Annotated, Any, Literal, Self
 
 from models_library.api_schemas_catalog.services import LatestServiceGet, ServiceGetV2
 from models_library.basic_regex import PUBLIC_VARIABLE_NAME_RE
@@ -39,14 +39,20 @@
 class Solver(BaseService):
     """A released solver with a specific version"""
 
-    maintainer: str = Field(..., description="Maintainer of the solver")
+    maintainer: Annotated[str, Field(description="Maintainer of the solver")]
+
+    version_display: Annotated[
+        str | None,
+        Field(description="A user-friendly or marketing name for the release."),
+    ] = None
 
     model_config = ConfigDict(
         extra="ignore",
         json_schema_extra={
             "example": {
                 "id": "simcore/services/comp/isolve",
                 "version": "2.1.1",
+                "version_display": "2.1.1-2023-10-01",
                 "title": "iSolve",
                 "description": "EM solver",
                 "maintainer": "info@itis.swiss",
@@ -56,31 +62,27 @@ class Solver(BaseService):
     )
 
     @classmethod
-    def create_from_image(cls, image_meta: ServiceMetaDataPublished) -> "Solver":
-        data = image_meta.model_dump(
-            include={"name", "key", "version", "description", "contact"},
-        )
+    def create_from_image(cls, image_meta: ServiceMetaDataPublished) -> Self:
         return cls(
-            id=data.pop("key"),
-            version=data.pop("version"),
-            title=data.pop("name"),
-            maintainer=data.pop("contact"),
+            id=image_meta.key,
+            version=image_meta.version,
+            title=image_meta.name,
+            description=image_meta.description,
+            maintainer=image_meta.contact,
+            version_display=image_meta.version_display,
             url=None,
-            **data,
         )
 
     @classmethod
-    def create_from_service(cls, service: ServiceGetV2 | LatestServiceGet) -> "Solver":
-        data = service.model_dump(
-            include={"name", "key", "version", "description", "contact"},
-        )
+    def create_from_service(cls, service: ServiceGetV2 | LatestServiceGet) -> Self:
         return cls(
-            id=data.pop("key"),
-            version=data.pop("version"),
-            title=data.pop("name"),
+            id=service.key,
+            version=service.version,
+            title=service.name,
+            description=service.description,
+            maintainer=service.contact or "UNDEFINED",
+            version_display=service.version_display,
             url=None,
-            maintainer=data.pop("contact"),
-            **data,
         )
 
     @classmethod
diff --git a/services/api-server/tests/unit/api_solvers/test_api_routers_solvers.py b/services/api-server/tests/unit/api_solvers/test_api_routers_solvers.py
