Deprecating Endpoints

Deprecating a command before removing it gives users a release cycle to move to its replacement. Add the replacement first, then mark the old command with deprecated=True and a deprecation warning object in @router.command. Both arguments are required together; deprecated=True without deprecation fails when the router module is imported.

from typing import Any

from openbb_core.app.deprecation import OpenBBDeprecationWarning
from openbb_core.app.model.obbject import OBBject
from openbb_core.app.router import Router

router = Router(prefix="", description="Utility commands.")


@router.command(methods=["GET"])
async def quote_spread(bid: float, ask: float) -> OBBject[dict[str, Any]]:
    """Calculate the mid price and spread of a quote."""
    return OBBject(results={"mid": (bid + ask) / 2, "spread": ask - bid})


@router.command(
    methods=["GET"],
    deprecated=True,
    deprecation=OpenBBDeprecationWarning(
        message="Use /my_tools/quote_spread instead.",
        since=(5, 0),
        expected_removal=(5, 2),
    ),
)
async def spread(bid: float, ask: float) -> OBBject[dict[str, Any]]:
    """Calculate the mid price and spread of a quote."""
    return await quote_spread(bid, ask)

OpenBBDeprecationWarning builds its full message from the three values: Use /my_tools/quote_spread instead. Deprecated in OpenBB Platform V5.0 to be removed in V5.2. A trailing period on message is dropped first. since defaults to the major and minor version of the installed openbb package (or openbb-core, when openbb is not installed), and expected_removal defaults to the next major version.

After openbb-build, the generated Python method is decorated as deprecated, so type checkers and IDEs flag calls to it, and every call emits a DeprecationWarning with the full message. In the REST API, the route is marked deprecated in the OpenAPI schema and the full message becomes its summary. The command keeps working until you remove it.

Record the planned removal version in your changelog or issue tracker, and remove the command in that release.