✨ Introduce changelog-driven FastAPI route configuration system #7620

pcrespov · 2025-04-30T16:21:44Z

What do these changes do?

The current release workflow for API entrypoints has proven to be error-prone and difficult to maintain. This PR introduces a new strategy aimed at improving the maintainability and documentation of our API endpoints. Note that it is built in common_library and so far it is not used in any service. If this is approach is accepted, the next step will be applying it in the api-server by replacing the existing method

Proposal

We extend the concept of changelogs—already used in api-server—to drive Fastapi route decorator configuration dynamically. This includes automatically setting properties such as include_in_schema, deprecated, and description based on a changelog and the current API_VERSION.

Benefits

Clearly encodes the lifecycle of each endpoint in one place.
Reduces manual overhead and potential for error in maintaining API versions.
Can plan the entire workflow in advance and the config will automatically change as we increase API_VERSION
Ensures consistent and up-to-date OpenAPI documentation.

Example

When working to release something, assuming API_VERSION<0.10, this entrypoint will not be included in the OpenAPI specs, but it will happen as soon as we version bump it to 0.10 (and we will see in the openapi.yaml)

from ..._meta import API_VERSION


@router.get(
     "/v1/something",
     response_model=SomethingModel,         
     **create_route_config(
        "This is a brand new something",
        changelog=[
            NewEndpoint("0.10.0"),
         ],
        current_version=API_VERSION,
    ):
async def get_something( ... )
     ...

In the following example the endpoint will be marked as deprecated as soon as API_VERSION >= 0.9.0 and excluded from the OpenAPI schema automatically when API_VERSION >= 0.9.0, as it has been marked retired

from ..._meta import API_VERSION

@router.get(
    "/v1/something",
    response_model=SomethingModel,
    **create_route_config(
        "This endpoint has a complex history",
        changelog=[
            NewEndpoint("0.5.0"),
            ChangedEndpoint("0.6.0", "Added authentication"),
            ChangedEndpoint("0.6.2", "Fixed a bug"),
            DeprecatedEndpoint(alternative_route="/v1/better-endpoint"),
            RetiredEndpoint("0.9.0", "Use the new endpoint instead"),
        ],
        current_version=API_VERSION,
    )
)
async def get_something(...):
    ...

Example, this code

will produce redoc documentation as follow:

Related issue/s

How to test

cd packages/common-library
make install-dev
pytest -vv tests/test_changelog.py

Dev-ops

None

codecov · 2025-04-30T16:23:21Z

Codecov Report

Attention: Patch coverage is 96.07843% with 4 lines in your changes missing coverage. Please review.

Project coverage is 89.04%. Comparing base (adc0218) to head (d1c397d).
Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #7620      +/-   ##
==========================================
+ Coverage   87.73%   89.04%   +1.30%     
==========================================
  Files        1786     1250     -536     
  Lines       68922    52721   -16201     
  Branches     1134      224     -910     
==========================================
- Hits        60472    46944   -13528     
+ Misses       8138     5704    -2434     
+ Partials      312       73     -239

Flag	Coverage Δ
integrationtests	`64.96% <ø> (+<0.01%)`	⬆️
unittests	`88.01% <96.07%> (+1.07%)`	⬆️

Components	Coverage Δ
api	`∅ <ø> (∅)`
pkg_aws_library	`∅ <ø> (∅)`
pkg_dask_task_models_library	`∅ <ø> (∅)`
pkg_models_library	`∅ <ø> (∅)`
pkg_notifications_library	`∅ <ø> (∅)`
pkg_postgres_database	`∅ <ø> (∅)`
pkg_service_integration	`∅ <ø> (∅)`
pkg_service_library	`∅ <ø> (∅)`
pkg_settings_library	`∅ <ø> (∅)`
pkg_simcore_sdk	`85.48% <ø> (-0.18%)`	⬇️
agent	`96.46% <ø> (ø)`
api_server	`92.50% <ø> (ø)`
autoscaling	`96.08% <ø> (ø)`
catalog	`92.64% <ø> (ø)`
clusters_keeper	`99.25% <ø> (ø)`
dask_sidecar	`91.37% <ø> (ø)`
datcore_adapter	`98.12% <ø> (ø)`
director	`76.89% <ø> (ø)`
director_v2	`91.18% <ø> (+0.04%)`	⬆️
dynamic_scheduler	`97.40% <ø> (ø)`
dynamic_sidecar	`90.15% <ø> (ø)`
efs_guardian	`89.79% <ø> (ø)`
invitations	`93.28% <ø> (ø)`
payments	`92.66% <ø> (ø)`
resource_usage_tracker	`89.12% <ø> (ø)`
storage	`87.67% <ø> (ø)`
webclient	`∅ <ø> (∅)`
webserver	`86.04% <ø> (+0.01%)`	⬆️

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update adc0218...d1c397d. Read the comment docs.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull Request Overview

This PR introduces a changelog-driven FastAPI route configuration system in the common-library, aiming to improve API endpoint maintainability and documentation. Key changes include:

Implementation of changelog entry classes (NewEndpoint, ChangedEndpoint, DeprecatedEndpoint, RetiredEndpoint) and related helper functions.
Introduction of create_route_config and create_route_description functions to automatically adjust route properties based on API_VERSION and changelog data.
Comprehensive test coverage added for validating changelog order and configuration outcomes.

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/common-library/tests/test_changelog.py	Adds tests to validate changelog entries and route configuration logic.
packages/common-library/src/common_library/changelog.py	Implements changelog entry classes and configuration helper functions.

pcrespov · 2025-05-01T14:49:43Z

@mergify queue

mergify · 2025-05-01T14:50:07Z

sanderegg

looking nice! thanks

packages/common-library/src/common_library/changelog.py

bisgaard-itis

This is definitely a good improvement. One challenge I see is that we don't know in advance what the next released version of the api-server is. What I suggest is that the Make target which we use to bump the version of the api-server will display the diff in the openapi-specs. I volunteer to set that up. And then at least one can manually inspect what a change in the version exposes/deprecated/retires. What do you think?

…onfiguration

…for deprecation logic

…outes

…constants, and add comprehensive tests for route configuration

…representation and enhance tests for route configuration

…roved consistency and type safety

pcrespov · 2025-05-02T15:50:48Z

@mergify queue

mergify · 2025-05-02T15:51:12Z

queue

🛑 The pull request has been merged manually

The pull request has been merged manually at 975c581

sonarqubecloud · 2025-05-05T07:31:43Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

pcrespov changed the title ~~✨ Mai/new changelog for apis~~ ✨ Maintenance: changelog for FastApi routes Apr 30, 2025

pcrespov self-assigned this Apr 30, 2025

pcrespov changed the title ~~✨ Maintenance: changelog for FastApi routes~~ ✨ Introduce changelog-driven FastAPI route configuration system Apr 30, 2025

pcrespov added the t:maintenance Some planned maintenance work label Apr 30, 2025

pcrespov marked this pull request as ready for review April 30, 2025 16:36

pcrespov requested a review from giancarloromeo as a code owner April 30, 2025 16:36

pcrespov requested review from GitHK, sanderegg, bisgaard-itis and Copilot April 30, 2025 16:37

Copilot AI reviewed Apr 30, 2025

View reviewed changes

pcrespov added this to the Pauwel Kwak milestone Apr 30, 2025

pcrespov added the 🤖-automerge marks PR as ready to be merged for Mergify label May 1, 2025

sanderegg approved these changes May 2, 2025

View reviewed changes

packages/common-library/src/common_library/changelog.py Show resolved Hide resolved

packages/common-library/src/common_library/changelog.py Show resolved Hide resolved

bisgaard-itis approved these changes May 2, 2025

View reviewed changes

pcrespov requested review from bisgaard-itis and matusdrobuliak66 May 2, 2025 15:16

pcrespov force-pushed the mai/new-changelog-for-apis branch from 3098f87 to 1700e54 Compare May 2, 2025 15:49

pcrespov added 9 commits May 2, 2025 17:50

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

44af0a7

…onfiguration

✨ Enhance changelog handling in route configuration and update tests …

7de9f94

…for deprecation logic

✨ Add changelog management classes and validation functions for API r…

3f9c566

…outes

revert

77094d7

✨ Refactor changelog management: update documentation, remove unused …

027aab2

…constants, and add comprehensive tests for route configuration

✨ Update DeprecatedEndpoint to include version information in string …

72d2ffa

…representation and enhance tests for route configuration

renamed removed by retired

38c677f

✨ Refactor changelog entry classes to use abstract base class for imp…

3366d1b

…roved consistency and type safety

@sanderegg review:newlines

045c8bd

@sanderegg review:newlines

dac49f5

pcrespov force-pushed the mai/new-changelog-for-apis branch from 1700e54 to dac49f5 Compare May 2, 2025 15:50

pcrespov enabled auto-merge (squash) May 2, 2025 15:50

giancarloromeo approved these changes May 5, 2025

View reviewed changes

Merge branch 'master' into mai/new-changelog-for-apis

d1c397d

pcrespov merged commit 975c581 into ITISFoundation:master May 5, 2025
94 of 96 checks passed

pcrespov deleted the mai/new-changelog-for-apis branch May 5, 2025 10:20

matusdrobuliak66 mentioned this pull request May 8, 2025

🚀 Release v1.82.0 #7573

Closed

34 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

✨ Introduce changelog-driven FastAPI route configuration system #7620

✨ Introduce changelog-driven FastAPI route configuration system #7620

Uh oh!

pcrespov commented Apr 30, 2025 •

edited

Loading

Uh oh!

codecov bot commented Apr 30, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

pcrespov commented May 1, 2025

Uh oh!

mergify bot commented May 1, 2025 •

edited

Loading

Uh oh!

sanderegg left a comment

Uh oh!

Uh oh!

Uh oh!

bisgaard-itis left a comment

Uh oh!

pcrespov commented May 2, 2025

Uh oh!

mergify bot commented May 2, 2025 •

edited

Loading

Uh oh!

sonarqubecloud bot commented May 5, 2025

Uh oh!

Uh oh!

Uh oh!

✨ Introduce changelog-driven FastAPI route configuration system #7620

✨ Introduce changelog-driven FastAPI route configuration system #7620

Uh oh!

Conversation

pcrespov commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What do these changes do?

Proposal

Benefits

Example

Related issue/s

How to test

Dev-ops

Uh oh!

codecov bot commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

pcrespov commented May 1, 2025

Uh oh!

mergify bot commented May 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟠 Waiting for conditions to match

Uh oh!

sanderegg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bisgaard-itis left a comment

Choose a reason for hiding this comment

Uh oh!

pcrespov commented May 2, 2025

Uh oh!

mergify bot commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛑 The pull request has been merged manually

Uh oh!

sonarqubecloud bot commented May 5, 2025

Quality Gate passed

Uh oh!

Uh oh!

Uh oh!

pcrespov commented Apr 30, 2025 •

edited

Loading

codecov bot commented Apr 30, 2025 •

edited

Loading

mergify bot commented May 1, 2025 •

edited

Loading

mergify bot commented May 2, 2025 •

edited

Loading