OpenBB Platform API Meta Package
This package is responsible for launching and configuring an OpenBB Platform environment, or FastAPI instance, to use as an OpenBB Workspace custom backend.
Installation
This package is included when you run pip install openbb; however, it also works as a standalone package
for creating new backends that are not part of the OpenBB GitHub repository.
To install as a standalone, use a Python environment between versions 3.9 and 3.12, inclusively.
pip install openbb-platform-api
Usage
See the keyword arguments section for parameters and descriptions.
Launch OpenBB Platform
To start the OpenBB Platform API, open a terminal, activate the environment where it is installed, and then enter:
openbb-api
This will launch a Fast API instance, via uvicorn, at http://127.0.0.1:6900
Uvicorn can be configured by adding keyword arguments, see the section below
Launch Custom App
To run your application as an OpenBB Workspace custom backend, add the path to the Python file with the FastAPI instance to the launch command.
openbb-api --app /Users/some_user/path/to/main.py
Example Application
This script will create a "markdown" widget with the returned text.
from openbb_platform_api.main import app
@app.get("/hello")
async def hello() -> str:
"""Widget Description Generated By Docstring"""
return "Hello, from OpenBB!"
Function arguments will populate as widget parameters.
from openbb_platform_api.main import app
from typing import Literal, Optional
@app.get("/hello")
async def hello(param1: Optional[str] = None, param2: Literal["Choice 1", "Choice 2"] = None, param3: bool = False) -> str:
"""Widget Description Generated By Docstring"""
if not param1 and not param2 and not param3:
return "Enter a parameter or make a choice!"
if param3:
return f"Param3 enabled!"
if param2:
return f"You selected: {param2}"
if param1:
return f"You entered: {param1}"
return "Nothing to return!"
Create a table widget by returning data shaped as a list of dictionaries (records)
from openbb_platform_api.main import app
@app.get("/hello")
async def hello() -> list:
"""Widget Description Generated By Docstring"""
return [{"Column 1": "Hello", "Column 2": "from OpenBB!"}]
Widget Config
Any value from the widgets.json structure can be passed into the @app decorator by including an openapi_extra dictionary with the key, "widget_config".
from openbb_platform_api.main import app
@app.get("/hello",
openapi_extra={
"widget_config": {
"data": {
"table": {
"columnsDefs": [
{"field": "Column 1", "headerName": "My Column", "headerTooltip": "Tooltip added!", "type": "text"}
]
}
}
}
}
)
async def hello() -> list:
"""Widget Description Generated By Docstring"""
return [{"Column 1": "Hello", "Column 2": "from OpenBB!"}]
Configurations for widgets.json supplied here will override any of the automatically generated content.
If the key does not exist, it will be created.
Auto-Generate ColumnsDefs
To generate ColumnsDefs for each field in the response data, return a list of Pydantic models with each column being assigned to Field.
Inherit the BaseModel from the openbb-core package by using the imports below.
Columns, by default, are presented in the order of insertion.
from openbb_platform_api.main import app
from openbb_core.provider.abstract.data import Data # Inherit this instead of pydantic.BaseModel to represent 1 row of data.
from pydantic import Field
class MyData(Data):
"""MyData Response Model."""
column_1: str = Field(title="Column 1", description="Description for Column 1") # 'description' will add the column header tooltip to your widget.
column_2: str = Field(title="Column 2", description="Description for Column 2")
@app.get("/hello")
async def hello() -> list[MyData]:
"""Widget Description Generated By Docstring"""
return [MyData.model_validate({"column_1": "Hello", "column_2": "from OpenBB!"})]
Keyword Arguments
The behavior of the script can be configured with the use of arguments and keyword arguments.
Launcher specific arguments:
--app Absolute path to the Python file with the target FastAPI instance. Default is the installed OpenBB Platform API.
--editable Flag to make widgets.json an editable file that can be modified during runtime. Default is 'false'.
--build If the file already exists, changes prompt action to overwrite/append/ignore. Only valid when --editable true.
--no-build Do not build the widgets.json file. Use this flag to load an existing widgets.json file without checking for updates.
--login Login to the OpenBB Platform.
--exclude JSON encoded list of API paths to exclude from widgets.json. Disable entire routes with '*' - e.g. '["/api/v1/*"]'.
--no-filter Do not filter out widgets in widget_settings.json file.
--widgets-path Absolute path to the widgets.json file. Default is ~/envs/{env}/assets/widgets.json. Supplying this sets --editable true.
--templates-path Absolute path to the workspace_templates.json file. Default is ~/OpenBBUserData/workspace_templates.json.
All other arguments will be passed to uvicorn. Here are the most common ones:
--host TEXT Host IP address or hostname.
[default: 127.0.0.1]
--port INTEGER Port number.
[default: 6900]
--ssl-keyfile TEXT SSL key file.
--ssl-certfile TEXT SSL certificate file.
--ssl-keyfile-password TEXT SSL keyfile password.
--ssl-version INTEGER SSL version to use.
(see stdlib ssl module's)
[default: 17]
--ssl-cert-reqs INTEGER Whether client certificate is required.
(see stdlib ssl module's)
[default: 0]
--ssl-ca-certs TEXT CA certificates file.
--ssl-ciphers TEXT Ciphers to use.
(see stdlib ssl module's)
[default: TLSv1]
Run uvicorn --help to get the full list of arguments.
API Over HTTPS
To run the API over the HTTPS protocol, you must first create a self-signed certificate and the associated key. After activating the environment, you can generate the files by entering this to the command line:
openssl req -x509 -days 3650 -out localhost.crt -keyout localhost.key -newkey rsa:4096 -nodes -sha256 -subj '/CN=localhost' -extensions EXT -config <( \
printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
Two files will be created, in the current working directory, that are passed as keyword arguments to the openbb-api entry point.
openbb-api --ssl_keyfile localhost.key --ssl_certfile localhost.crt
Note: Adjust the command to include the full path to the file if the current working directory is not where they are located.
The certificate - localhost.crt - will need to be added to system's trust store. The process for this will depend on the operating system and the user account privilege.
A quick solution is to visit the server's URL, show the details of the warning, and choose to continue anyways.
Contact the system administrator if you are using a work device and require additional permissions to complete the configuration.
Location of widgets.json
When launched as openbb-api --editiable, a file will be stored to disk. By default, that location is:
/Path/to/environments/envs/obb/assets/widgets.json
The file can be manually edited and served without the build process by passing --editable --no-build to the API launch script.
openbb-api --editable --no-build
If you would like to construct this file manually, create the file and define the path as an argument.
openbb-api --widgets-path /Users/some_user/path/to/widgets.json
Location of templates.json
By default, the location is:
~/OpenBBUserData/workspace_templates.json
This can be changed by adding the path as an argument.
openbb-api --templates-path /Users/some_user/path/to/workspace_templates.json
The OpenBB Workspace allows you to export the current dashboard layout - when it is a custom backend - as a template.
To export the layout, right-click on the dashboard and select, "Export Template".
A JSON dictionary will be exported. Insert the contents of the export into "~/OpenBBUserData/workspace_templates.json" by pasting between the JSON list markers, [ ].
If there are more than one, add a comma between each dictionary entry.