From 675480972dbe1070fb0477ee285cf2f5b03dd06e Mon Sep 17 00:00:00 2001 From: Theodore Aptekarev Date: Fri, 15 Dec 2023 16:14:03 +0100 Subject: [PATCH] Add REST API docs page with advanced settings configuration (#5890) * Don't mention docker in a list of python envs * Create a REST API page * Update docs to get api keys from the hub * Update installation instructions * Mention requirement of poetry and toml in source installation section * move rest page up to the top. and add url to google colab example notebook --------- Co-authored-by: Danglewood <85772166+deeleeramone@users.noreply.github.com> --- .secrets.baseline | 10 +- website/content/platform/installation.md | 30 +++-- website/content/platform/usage/index.md | 77 +++-------- website/content/platform/usage/rest_api.md | 142 +++++++++++++++++++++ 4 files changed, 184 insertions(+), 75 deletions(-) create mode 100644 website/content/platform/usage/rest_api.md diff --git a/.secrets.baseline b/.secrets.baseline index f44eb0b419d..b13e768abed 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -115,17 +115,21 @@ { "path": "detect_secrets.filters.regex.should_exclude_line", "pattern": [ - ".*example.*" + ".*example.*", + ".*_api_key.*" ] }, { "path": "detect_secrets.filters.regex.should_exclude_secret", "pattern": [ "example", - "REPLACE_ME" + "REPLACE_ME", + "my_email", + "my_password", + "my_pat" ] } ], "results": {}, - "generated_at": "2022-11-16T18:07:51Z" + "generated_at": "2023-12-14T18:07:51Z" } diff --git a/website/content/platform/installation.md b/website/content/platform/installation.md index f9e662108ef..214664c99d1 100644 --- a/website/content/platform/installation.md +++ b/website/content/platform/installation.md @@ -49,23 +49,19 @@ Linux users should run the command line update for the package manager, prior to ## Supported Environments -The OpenBB Platform is installed within a Python virtual environment. It is compatible with versions of Python between 3.8 and 3.11, inclusively. The method for creating the environment will be a matter of user preference, from the command line - [Conda](https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html), [venv](https://docs.python.org/3/library/venv.html), [Docker](https://hub.docker.com/), etc. - or in a code editor and IDE - [VS Code](https://code.visualstudio.com/docs/languages/python), [PyCharm](https://www.jetbrains.com/pycharm/), [Jupyter](https://jupyter.org/). +The OpenBB Platform is installed within a Python virtual environment. It is compatible with versions of Python between 3.8 and 3.11, inclusively. The method for creating the environment will be a matter of user preference, from the command line - [Conda](https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html), [venv](https://docs.python.org/3/library/venv.html), etc. - or in a code editor and IDE - [VS Code](https://code.visualstudio.com/docs/languages/python), [PyCharm](https://www.jetbrains.com/pycharm/), [Jupyter](https://jupyter.org/). -[Docker](/platform/installation#docker) builds the environment during the installation process, skip ahead to the specific section [below](/platform/installation#docker). +If you're interested in using the [Docker](/platform/installation#docker) container, skip ahead to the specific section [below](/platform/installation#docker). For those new to Python, [this article](https://www.infoworld.com/article/3306656/python-virtualenv-and-venv-dos-and-donts.html) shares some tips on getting started and why environments are important. See [this guide](https://code.visualstudio.com/docs/python/environments) for creating a Python environment in VS Code. -With the container created, and activated, begin the installation process. +With the environment created, and activated, begin the installation process. ## Installation -Before installation, update the package manager so that `pip` is current, then create the environment with the desired version of Python and install the following packages: - -```console -pip install poetry toml -``` +Before installation, update the package manager so that `pip` is current, then create the environment with the desired version of Python. :::note Installing packages directly to the system Python or `base` environment is not recommended. Create a new environment first (can be any name, using openbb here for example). @@ -103,10 +99,10 @@ pip install openbb[charting] pip install openbb[ta] ``` -Or import a single provider: +Or install a single provider: ```console -pip install openbb-yfinance +pip install openbb[yfinance] ``` From your python interpreter, import the OpenBB Platform: @@ -130,7 +126,7 @@ When the package is imported, any installed extensions will be discovered, impor Currently if you wish to have the bare-bones openbb package with no extensions or providers, you can install with: ```console -pip install openbb --no-deps +pip install openbb-core && pip install openbb --no-deps ``` ::: @@ -179,6 +175,12 @@ Then, `cd` into the directory: cd openbb_platform ``` +Install required packages + +```console +pip install poetry toml +``` + Finally, run the developer installation script: ```console @@ -196,7 +198,7 @@ With a fresh installation, and upon installing or uninstalling extensions, the P ```console python -import openbb +from openbb import obb exit() ``` @@ -220,6 +222,8 @@ Start the REST API with: uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload ``` +See more information about using the REST API in the [usage section](/platform/usage/rest_api) + ## Hub Synchronization Once you have installed the OpenBB Platform with the desired providers and extensions, you can synchronize with the [OpenBB Hub](my.openbb.co). The main benefit of this is that you can use your single login to access your saved credentials and preferences from any instance. To login, you can use the `login` method, either using your email and password: @@ -238,7 +242,7 @@ obb.account.login(pat='my_pat_here') The documentation and packages are kept in the `/website` folder, at the base of the repository. Navigate there to install the dependencies and start the development server. -#### Node.js +### Node.js - [Node.js](https://nodejs.org/en/) >= 16.13.0 To check if Node.js installed, run this command: diff --git a/website/content/platform/usage/index.md b/website/content/platform/usage/index.md index f8669f46773..3483a3662d8 100644 --- a/website/content/platform/usage/index.md +++ b/website/content/platform/usage/index.md @@ -27,7 +27,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx'; -At its base, the OpenBB Platform supplies core architecture and services for connecting data providers and extensions, consumable as a Python client and Fast API. The extension framework provides interoperability between as many, or few, services required. Optional extras are not included with the base installation, and these include: +At its base, the OpenBB Platform supplies core architecture and services for connecting data providers and extensions, consumable through the Python client or the Fast API. The extension framework provides interoperability between as many, or few, services required. Optional extras are not included with the base installation, and these include: - Charting libraries and views - Data cleaning @@ -37,29 +37,27 @@ At its base, the OpenBB Platform supplies core architecture and services for con ## Authorization -By default, authorization is not required to initialize and use the core services. Most data providers, however, require an API key to access their data. They can be stored locally, or securely on the OpenBB Hub for convenient remote access. Refer to our Developer Guidelines for best practices within a production environment. +By default, authorization is not required to initialize and use the core services. Most data providers, however, require an API key to access their data. The API keys can be stored locally, or securely on the OpenBB Hub for convenient remote access. Refer to our Developer Guidelines for best practices within a production environment. ### OpenBB Hub -Data provider credentials and user preferences can be securely stored on the OpenBB Hub and accessed via a revokable Personal Access Token (PAT). Login to the [Hub](https://my.openbb.co/) to manage this method of remote authorization. +Data provider credentials and user preferences can be securely stored on the OpenBB Hub and accessed in Python using a revokable Personal Access Token (PAT). Login to the [Hub](https://my.openbb.co/) to manage this method of remote authorization. -#### Python Client +The OpenBB Hub is a convenient solution for accessing data in temporary Python environments, like Google Colab ([example notebook](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/examples/googleColab.ipynb)). Login with: -The OpenBB Hub is a convenient solution for accessing data in temporary environments, like Google Colab. Login using the Python client with: - -```jupyterpython +```python from openbb import obb # Login with personal access token -obb.account.login(pat="your_pat", remember_me=True) +obb.account.login(pat="my_pat", remember_me=True) -# Login with email and password -obb.account.login(email="your_email", password="your_password", remember_me=True) +# Alternatively, login with email and password +obb.account.login(email="my_email", password="my_password", remember_me=True) # Change a credential -obb.user.credentials.polygon_api_key = "new_key" +obb.user.credentials.polygon_api_key = "my_api_key" -# Save account changes +# Save account changes to the Hub obb.account.save() # Refresh account with latest changes @@ -71,45 +69,6 @@ obb.account.logout() Set `remember_me` as `False` to discard all credentials at the end of the session. -### Fast API - -Activate the Python environment and then start the server from a Terminal command line with: - -```console -uvicorn openbb_core.api.rest_api:app -``` - -To use the Fast API documentation page, navigate to [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). By default, no authorization is required. Basic authorization can be enabled with environment variables. In the home folder, along with `user_settings.json`, create a new file, `.env`, if it does not yet exist. - -```.env -OPENBB_API_AUTH="True" -OPENBB_API_USERNAME="some_user" -OPENBB_API_PASSWORD="some_pass" -``` - -The application will expect a header that contains username and password in the form of `Basic `, where "username:password" is encoded in Base64. Pass this in every request to the API inside the headers "Authorization" field. - -```python -import base64 -import requests - -msg = "some_user:some_pass" -msg_bytes = msg.encode('ascii') -base64_bytes = base64.b64encode(msg_bytes) -base64_msg = base64_bytes.decode('ascii') - - -symbol="SPY" -url = f"http://127.0.0.1:8000/api/v1/equity/price/quote?provider=intrinio&symbol={symbol}&source=intrinio_mx" -headers = {"accept": "application/json", "Authorization": f"Basic {base64_msg}"} - -response = requests.get(url=url, headers=headers) - -response.json() -``` - -Refer to the Developer Guidelines for custom authorization procedures. - ### Local Environment Credentials and user preferences are stored locally, `~/.openbb_platform/`, as a JSON file, `user_settings.json`. It is read upon initializing the Python client, or when the Fast API is authorized. If the file does not exist, create it with any text editor. The schema below can be copy/pasted if required, providers not listed here are added using the same format: @@ -117,13 +76,13 @@ Credentials and user preferences are stored locally, `~/.openbb_platform/`, as ```json { "credentials": { - "fmp_api_key": "REPLACE", - "polygon_api_key": "REPLACE", - "benzinga_api_key": "REPLACE", - "fred_api_key": "REPLACE", - "nasdaq_api_key": "REPLACE", - "intrinio_api_key": "REPLACE", - "alpha_vantage_api_key": "REPLACE", + "fmp_api_key": "REPLACE_ME", + "polygon_api_key": "REPLACE_ME", + "benzinga_api_key": "REPLACE_ME", + "fred_api_key": "REPLACE_ME", + "nasdaq_api_key": "REPLACE_ME", + "intrinio_api_key": "REPLACE_ME", + "alpha_vantage_api_key": "REPLACE_ME", } } ``` @@ -131,7 +90,7 @@ Credentials and user preferences are stored locally, `~/.openbb_platform/`, as To set keys from the Python client for the current session only, access the Credentials class: ```python -obb.user.credentials.intrinio_api_key = "REPLACE_WITH_KEY" +obb.user.credentials.intrinio_api_key = "my_api_key" ``` ## Environment Variables diff --git a/website/content/platform/usage/rest_api.md b/website/content/platform/usage/rest_api.md new file mode 100644 index 00000000000..bb1ab77fffc --- /dev/null +++ b/website/content/platform/usage/rest_api.md @@ -0,0 +1,142 @@ +--- +title: REST API +sidebar_position: 1 +description: Learn how to configure and deploy the OpenBB Platform's REST API using FastAPI, including detailed guidelines on API documentation, authorization, CORS settings, and server configurations. +keywords: +- OpenBB Platform +- REST API +- FastAPI +- API Documentation +- API Authorization +- CORS Configuration +- Server Settings +- API Deployment +- Swagger Documentation +- Basic Auth +- API Security +- System Settings JSON +- API Keys +- Public Internet Deployment +- Production Deployment +- API Endpoints +- Uvicorn Command +- Base64 Encoding +- HTTP Headers +- Python Requests +- Local Network API +- OpenAPI JSON +--- + +The OpenBB Platform comes with a FastAPI application that serves platform commands as REST API endpoints. + +Activate the Python environment and then start the server from a Terminal command line with: + +```console +uvicorn openbb_core.api.rest_api:app +``` + +You can add arguments that are supported by `uvicorn` to customize how the API is launched. +For example this command will be useful if you are developing. It will launch the API in a way it's reachable on your local network and reload every time the code changes: + +```console +uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload +``` + +To learn more about how you can run the API in different scenarios refer to [uvicorn's documentation](https://www.uvicorn.org/#command-line-options) + +## API Documentation + +The Fast API app comes with a swagger documentation page. When running the API locally, navigate to [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). + +The API Docs provide interactive descriptions of all available endpoints that you can call right from the documentation web page. + +## Data API Keys + +The API keys to your data providers are loaded from the `~/.openbb_platform/user_settings.json` file. You can find more information about the structure of the file and environment variables in the [Local Environment](/platform/usage#local-environment) section. + +## API Authorization + +By default, no authorization is required. Basic authorization can be enabled with environment variables. In the `~/.openbb_platform` folder, next to the `user_settings.json`, create a new file, `.env`, if it does not yet exist. Set your Basic Auth credentials. + +```.env +OPENBB_API_AUTH="True" +OPENBB_API_USERNAME="my_email" +OPENBB_API_PASSWORD="my_password" +``` + +The application will expect a header that contains username and password in the form of `Basic `, where "username:password" is encoded in Base64. Pass this in every request to the API inside the headers "Authorization" field. + +Here is an example of calling the API that has Basic Authorization enabled from python. + +```python +import base64 +import requests + +msg = "some_user:some_pass" +msg_bytes = msg.encode('ascii') +base64_bytes = base64.b64encode(msg_bytes) +base64_msg = base64_bytes.decode('ascii') + + +symbol="SPY" +url = f"http://127.0.0.1:8000/api/v1/equity/price/quote?provider=intrinio&symbol={symbol}&source=intrinio_mx" +headers = {"accept": "application/json", "Authorization": f"Basic {base64_msg}"} + +response = requests.get(url=url, headers=headers) + +response.json() +``` + +Refer to the Developer Guidelines for custom authorization procedures. + +## Advanced API Settings + +When deploying the API to the public internet, it's crucial to configure it in a way you ensure the application functions correctly and securely. Two critical aspects to consider are Cross-Origin Resource Sharing (CORS) and the configuration of the "servers" list. + +The configuration for these settings is managed through the `system_settings.json` file, which should be located in the same directory as your `user_settings.json`. This JSON file allows you to specify various settings that affect the behavior of the API. Here's an example structure of the `system_settings.json` file: + +```json +{ + "api_settings": { + "version": "1", + "title": "OpenBB Platform API", + "description": "This is the OpenBB Platform API.", + "terms_of_service": "http://example.com/terms/", + "contact_name": "OpenBB Team", + "contact_url": "https://openbb.co", + "contact_email": "hello@openbb.co", + "license_name": "MIT", + "license_url": "https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/LICENSE", + "servers": [ + { + "url": "http://localhost:8000", + "description": "Local OpenBB development server" + } + ], + "cors": { + "allow_origins": [ + "*" + ], + "allow_methods": [ + "*" + ], + "allow_headers": [ + "*" + ] + }, + "prefix": "/api/v1" + } +} +``` + +## CORS Configuration + +The cors section within the api_settings is particularly important for web applications. It defines the rules for which external domains are allowed to access your API. + +In the example above, the settings are permissive ("\*" for origins, methods, and headers), which means any external domain can request resources from your API. This setting might be suitable for development, but when deploying to public internet, you should specify the exact domains, methods, and headers to tighten security. + +## Servers List + +The servers array is used to specify the different environments where your API can be accessed. + +In the example, there is only one server defined, which is the local development server. For deployment to public internet, you would add an entry for the public server URL and any other environments where your API is accessible.