Refinement

Author: pbv0

docs/docs/fastapi/building_endpoints/_category_.json

@@ -1,4 +1,4 @@
 {
-    "label": "Building Endpoints",
-    "position": 2
-}
+  "label": "Endpoint examples",
+  "position": 2
+}

docs/docs/fastapi/building_endpoints/tables_insert.mdx

@@ -7,14 +7,15 @@ sidebar_position: 2
 This recipe demonstrates how to insert data into a Databricks [Unity Catalog table](https://docs.databricks.com/aws/en/tables/) from a FastAPI application using the [Databricks SQL Connector](https://docs.databricks.com/en/dev-tools/python-sql-connector.html).
 
 :::info
-In this example, we set up our API to be called using the `POST` HTTP method which is the standard choice for creating new resources in REST APIs as defined in RFC 7231. 
-Unlike `GET`, POST is not idempotent - making the same request multiple times may create multiple resources.  
+In this example, we set up our API to be called using the `POST` HTTP method which is the standard choice for creating new resources in REST APIs as defined in RFC 7231.
+Unlike `GET`, POST is not idempotent - making the same request multiple times may create multiple resources.
 
 POST requests are typically used when submitting data to be processed or when creating new resources, with the request body containing the data to be added.
 
 For detailed specifications, refer to [RFC 7231 Section 4.3.3](https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.3) which defines the POST method's semantics and requirements.
 
 :::
+
 ## Code snippet
 
 ```python title="app.py"
@@ -102,14 +103,16 @@ async def insert_table_data(request: Request):
 
 :::warning
 
-The above example is shortened for brevity and skips best practice implementation.  
-We encourage the reader to review and run the optimized FastAPI application code provided in the cookbook repository.
+The above example is shortened for brevity and not suitable for production use.
+You can find a more advanced sample in the databricks-apps-cookbook GitHub repository.
 
 :::
 
 ### Example Usage
+
 In this example, we will create the following Unity Catalog table called `my_catalog.my_schema.trips` via Databricks SQL Editor.  
-It is assumed that the user/service principal identity has the appropriate Unity Catalog grants to make changes as required.  
+It is assumed that the user/service principal identity has the appropriate Unity Catalog grants to make changes as required.
+
 ```sql
 CREATE OR REPLACE TABLE my_catalog.my_schema.trips (
   trip_id INT,
@@ -178,7 +181,9 @@ response = requests.post(
 )
 print(response.json())
 ```
+
 If the request was successful, you will get the following output in your terminal:
+
 ```shell
 {'data': [{'trip_id': 1, 'passenger_count': 1, 'trip_distance': 10.0, 'pickup_datetime': '2024-01-01 12:00:00', 'dropoff_datetime': '2024-01-01 12:10:00', 'payment_type': 'credit_card', 'fare_amount': 15.0, 'tip_amount': 2.0}, {'trip_id': 2, 'passenger_count': 1, 'trip_distance': 86.0, 'pickup_datetime': '2024-01-01 14:00:00', 'dropoff_datetime': '2024-01-01 15:13:00', 'payment_type': 'cash', 'fare_amount': 15.0, 'tip_amount': 3.0}, {'trip_id': 3, 'passenger_count': 1, 'trip_distance': 6.0, 'pickup_datetime': '2024-01-01 15:31:00', 'dropoff_datetime': '2024-01-01 15:45:00', 'payment_type': 'cash', 'fare_amount': 15.0, 'tip_amount': 3.0}], 'count': 3, 'total': 3}
 ```
@@ -209,4 +214,4 @@ databricks-sdk
 databricks-sql-connector
 fastapi
 uvicorn
-``` 
+```

docs/docs/fastapi/building_endpoints/tables_read.mdx

@@ -7,13 +7,14 @@ sidebar_position: 1
 This recipe demonstrates how to query Databricks [Unity Catalog tables](https://docs.databricks.com/aws/en/tables/) from a FastAPI application using the [Databricks SQL Connector](https://docs.databricks.com/en/dev-tools/python-sql-connector.html).
 
 :::info
-In this example, we set up our API to be called using the `GET` HTTP method which is the standard choice for reading data in REST APIs as defined in RFC 7231. It's designed to be safe (non-modifying) and idempotent, making it ideal for data retrieval operations.   
+In this example, we set up our API to be called using the `GET` HTTP method which is the standard choice for reading data in REST APIs as defined in RFC 7231. It's designed to be safe (non-modifying) and idempotent, making it ideal for data retrieval operations.
 
-GET requests are cacheable by default, improving performance, and their parameters are URL-encoded, making them bookmarkable and shareable.   
+GET requests are cacheable by default, improving performance, and their parameters are URL-encoded, making them bookmarkable and shareable.
 
 For detailed specifications, refer to [RFC 7231 Section 4.3.1](https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1) which defines the GET method's semantics and requirements.
 
 :::
+
 ## Code snippet
 
 ```python title="app.py"
@@ -69,20 +70,21 @@ def table(
 
 :::warning
 
-The above example is shortened for brevity and skips best practice implementation.  
-We encourage the reader to review and run the optimized FastAPI application code provided in the cookbook repository.
+The above example is shortened for brevity and not suitable for production use.
+You can find a more advanced sample in the databricks-apps-cookbook GitHub repository.
 
 :::
 
 ### Example Usage
-The query below retrieves data from the `system.billing.usage` [table](https://docs.databricks.com/aws/en/admin/system-tables/billing) via the above code snippet.  
-Kindly note that we need to encode the `sql_query` contents when making the API request.
 
+The query below retrieves data from the [`system.billing.usage` table](https://docs.databricks.com/aws/en/admin/system-tables/billing) via the above code snippet.  
+Note that we need to encode the `sql_query` contents when making the API request.
 
 ```shell
 curl -X GET "https://your-app-url/api/v1/table?sql_query=SELECT%20%2A%20FROM%20system.billing.usage%20LIMIT%201" \
   -H "Authorization: Bearer YOUR_DATABRICKS_TOKEN" | jq
 ```
+
 ```json
 {
   "results": [
@@ -176,4 +178,4 @@ databricks-sdk
 databricks-sql-connector
 fastapi
 uvicorn
-``` 
+```

docs/docs/fastapi/getting_started/connections/_category_.json

@@ -4,25 +4,24 @@ sidebar_position: 4
 
 # Connect Databricks App to Databricks App
 
-This recipe demonstrates how to connect one Databricks App to another Databricks App.
+This recipe demonstrates how to connect from a Databricks App to an API hosted as another Databricks App.
 
 :::info
 
-This is another type of Machine-to-Machine (M2M) connectivity; Databricks Apps provisions a dedicated Service Principal per application slot which should be used for the purposes of security isolation, authentication, and authorization.
+This is another type of Machine-to-Machine (M2M) connectivity. As each Databricks App is assigned a dedicated [service principal](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) upon creation, you should use this service principal's credentials when interacting with any Databricks service, including other Databricks Apps.
 
 :::
 
-
 ## Code snippet
 
-Under the Databricks Apps runtime, environment variables for `DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, and `DATABRICKS_CLIENT_SECRET` are present and associated with the App service principal.
+In the Databricks Apps environment, environment variables for `DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, and `DATABRICKS_CLIENT_SECRET` are are automatically set based on the app's workspace and assigned service principal. Therefore, you do not need to explicitly specify these values in the following code:
 
 ```python
 from databricks.sdk import WorkspaceClient
 import requests
 
-# DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET implicitly present under env
-wc = WorkspaceClient() 
+# DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET available in environemnt
+wc = WorkspaceClient()
 headers = wc.config.authenticate() # Contains Bearer Token
 
 response = requests.get(
@@ -42,8 +41,7 @@ For Databricks App connectivity and authentication, the connecting App [service
 - [Databricks SDK for Python](https://pypi.org/project/databricks-sdk/) - `databricks-sdk`
 - [Requests](https://pypi.org/project/requests/) - `requests`
 
-
 ```python title="requirements.txt"
 databricks-sdk
 requests
-``` 
+```

docs/docs/fastapi/getting_started/connections/connect_from_app.mdx

@@ -2,22 +2,21 @@
 sidebar_position: 3
 ---
 
-# Connect External App to Databricks App
+# Connect external app to Databricks App
 
-This recipe demonstrates how to connect your external application to a deployed Databricks App.
+This recipe demonstrates how to connect from your externally hosted application to an API deployed as a Databricks App.
 
 :::info
 
-This connection methodology is regarded as Machine-to-Machine (M2M) and customers are generally advised to use a Databricks [Service Principal](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) as per security best practices.
+This connectivity option is called Machine-to-Machine (M2M) and requires you to set up a Databricks [service principal](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) as per security best practices.
 
 :::
 
-
 ## Code snippet
 
-The example below requires a valid databricks workspace host, client id, and client secret.  
+The example below requires you to input a valid databricks workspace host URl as well as [service principal](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) client id and client secret when instantiating the `WorkspaceClient`.
 
-Alternatively, they can be provided as environment variables `DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, and `DATABRICKS_CLIENT_SECRET` respectively without needing to be used within `WorkspaceClient()`.
+Alternatively, you can set up these values as environment variables `DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, and `DATABRICKS_CLIENT_SECRET`. The `WorkspaceClient` will auomatically pick up these environemnt variables.
 
 ```python
 from databricks.sdk import WorkspaceClient
@@ -27,7 +26,7 @@ wc = WorkspaceClient(
     host="https://<DATABRICKS_HOST>",
     client_id="<DATABRICKS_CLIENT_ID>",
     client_secret="<DATABRICKS_CLIENT_SECRET>"
-) 
+)
 headers = wc.config.authenticate() # Contains Bearer Token
 
 response = requests.get(
@@ -47,8 +46,7 @@ For external app connectivity and authentication, the connecting [service princi
 - [Databricks SDK for Python](https://pypi.org/project/databricks-sdk/) - `databricks-sdk`
 - [Requests](https://pypi.org/project/requests/) - `requests`
 
-
 ```python title="requirements.txt"
 databricks-sdk
 requests
-``` 
+```

docs/docs/fastapi/getting_started/connections/connect_from_external.mdx

@@ -2,32 +2,33 @@
 sidebar_position: 2
 ---
 
-# Connect Local Machine to Databricks App
+# Connect local machine to Databricks App
 
-This recipe demonstrates how to connect from your local machine to a deployed Databricks App.
+This recipe demonstrates how to connect from your local machine to an API deployed as a Databricks App.
 
 :::warning
 
-The FastAPI application running on http://127.0.0.1:8000 does not require a [valid bearer token](https://docs.databricks.com/aws/en/dev-tools/auth/#databricks-authorization-methods) but only when deployed on Databricks Apps.
-This token is required for accessing Databricks Apps via the secured HTTPS URL with `/api` endpoints.  
+While the FastAPI application running locally on http://127.0.0.1:8000 does not require a [valid bearer token](https://docs.databricks.com/aws/en/dev-tools/auth/#databricks-authorization-methods), this token is required for accessing Databricks Apps via the secured HTTPS URL with `/api` endpoints.
 
 :::
 
 ## Generate OAuth2 Bearer token
+
 The easiest method to generate a valid token is to use the [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial) which allows you to authenticate with the workspace where the Databricks App is hosted.
 
+You can log in to a workspace via the following CLI command:
 
-Users can log into a workspace via the CLI command:
 ```bash
 databricks auth login --host https://<databricks-workspace-url> --profile my-env
 ```
 
 Upon logging in successfully via the browser, you will see that your profile has been saved. This is helpful if you need to test your app across multiple environments.
+
 ```bash
 Profile my-env was successfully saved
 ```
 
-A bearer token can then be generated with a limited TTL; temporarily store the `access_token` details for use later on.
+A bearer token can then be generated with a limited time-to-live. Make sure to temporarily store the `access_token` details for use later on.
 
 ```bash
 databricks auth token --profile my-env
@@ -61,7 +62,7 @@ response = requests.get(
 print(response.json())
 ```
 
-If you would like to avoid storing the token in your code, you can leverage the profile you have created using the Databricks CLI through the Databricks Python SDK directly.
+If you would like to avoid storing the token in your code, you can leverage the profile you have created using the Databricks CLI through the [Databricks SDK for Python](https://databricks-sdk-py.readthedocs.io/en/latest/) directly.
 
 ```python
 from databricks.sdk.core import Config
@@ -88,8 +89,7 @@ For local connectivity and authentication, the connecting user(s)/group(s) needs
 - [Databricks SDK for Python](https://pypi.org/project/databricks-sdk/) - `databricks-sdk`
 - [Requests](https://pypi.org/project/requests/) - `requests`
 
-
 ```python title="requirements.txt"
 databricks-sdk
 requests
-``` 
+```

docs/docs/fastapi/getting_started/connections/connect_from_local.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_position: 3
+---
+
+# Connect to a FastAPI app
+
+There are several options to consider when connecting to a deployed Databricks App.
+
+| Option                                                                                            | Use-Case                                                                                                        |
+| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| [Local Machine to Databricks App](/docs/fastapi/getting_started/connections/connect_from_local)   | Development & testing, exploratory work                                                                         |
+| [External App to Databricks App](/docs/fastapi/getting_started/connections/connect_from_external) | Consume Databricks services from an external application via an API hosted in Databricks Apps                   |
+| [Databricks App to Databricks App](/docs/fastapi/getting_started/connections/connect_from_app)    | Internal consumption of Databricks services across workspaces (e.g. app federation), microservices architecture |