Documentation improvements for Public Preview (#1253)

## Why make this change?

Improve documentation

## What is this change?

Updating TOC and adding troubleshooting

## How was this tested?

N/A

## Sample Request(s)

N/A

Author: yorek

README.md

@@ -9,24 +9,29 @@ Latest version of Data API builder is  **0.5.34** [What's new?](./docs/whats-new
 
 **Data API builder for Azure Databases provides modern REST and GraphQL endpoints to your Azure Databases.**
 
-With Data API builder, database objects can be exposed via REST or GraphQL endpoints so that your data can be accessed using modern techniques on any platform, any language, and any device. With an integrated and flexible policy engine, granular security is assured; integrated with Azure SQL, SQL Server, PostgreSQL, MySQL and Cosmos DB, gives developers an efficiency boost like never seen before.
+With data API builder, database objects can be exposed via REST or GraphQL endpoints so that your data can be accessed using modern techniques on any platform, any language, and any device. With an integrated and flexible policy engine, native support for common behavior like pagination, filtering, projection and sorting, the creation of CRUD backend services can be done in minutes instead of hours or days, giving developers an efficiency boost like never seen before.
 
-![Data API builder Architecture Overview Diagram](./docs/media/data-api-builder-overview.png)
+Data API builder is Open Source and works on any platform. It can be executed on-premises, in a container or as a Managed Service in Azure, via the new [Database Connection](https://learn.microsoft.com/azure/static-web-apps/database-overview) feature available in Azure Static Web Apps.
+
+![Data API builder Architecture Overview Diagram](./docs/media/dab-architecture-overview.png)
 
 ## Features
 
 - Allow collections, tables, views and stored procedures to be accessed via REST and GraphQL
-- Support authentication via JWT and EasyAuth
+- Support authentication via OAuth2/JWT
+- Support for EasyAuth when running in Azure
 - Role-based authorization using received claims
 - Item-level security via policy expressions
 - REST
   - CRUD operations via POST, GET, PUT, PATCH, DELETE
-  - filtering, sorting and pagination
+  - Filtering, sorting and pagination
 - GraphQL
-  - queries and mutations
-  - filtering, sorting and pagination
-  - relationship navigation
+  - Queries and mutations
+  - Filtering, sorting and pagination
+  - Relationship navigation
 - Easy development via dedicated CLI
+- Full integration with Static Web Apps via Database Connection feature when running in Azure
+- Open Source
 
 ## Getting Started
 
@@ -36,9 +41,11 @@ To get started quickly with Data API builder for Azure Databases, you can use th
 
 Documentation is available in the [`docs`](./docs) folder.
 
-## Limitations
+## Samples
+
+Several samples are available already. In the `./samples` folder, you'll find the code needed to follow the [Getting Started](./docs/getting-started/getting-started.md) tutorial.
 
-- JWT only supports Azure AD
+More samples, including end-to-end samples using the most common frontend framework, are available in the [https://github.com/Azure-Samples/data-api-builder] repository.
 
 ## Known Issues
 

docker/docker-compose-cosmos.yml

@@ -4,7 +4,7 @@
 version: "3.9"
 services:
   hawaii:
-    image: "hawaiiacr.azurecr.io/dab/refs/heads/main:latest"
+    image: "mcr.microsoft.com/azure-databases/data-api-builder:latest"
     ports:
       - "5000:5000"
     volumes:

docker/docker-compose-mssql.yml

@@ -4,7 +4,7 @@
 version: "3.9"
 services:
   hawaii:
-    image: "hawaiiacr.azurecr.io/dab/refs/heads/main:latest"
+    image: "mcr.microsoft.com/azure-databases/data-api-builder:latest"
     ports:
       - "5000:5000"
     volumes:

docker/docker-compose-mysql.yml

@@ -4,7 +4,7 @@
 version: "3.9"
 services:
   hawaii:
-    image: "hawaiiacr.azurecr.io/dab/refs/heads/main:latest"
+    image: "mcr.microsoft.com/azure-databases/data-api-builder:latest"
     ports:
       - "5000:5000"
     volumes:

docker/docker-compose-postgresql.yml

@@ -4,7 +4,7 @@
 version: "3.9"
 services:
   hawaii:
-    image: "hawaiiacr.azurecr.io/dab/refs/heads/main:latest"
+    image: "mcr.microsoft.com/azure-databases/data-api-builder:latest"
     ports:
       - "5000:5000"
     volumes:

docs/authentication-azure-ad.md

@@ -85,19 +85,19 @@ Where the`APP_ID` is the "Application (client) ID" and the `TENANT_ID` is the "D
 
 Make sure you are logged in to AZ CLI with the account that you want to use to authenticate against Data API builder.
 
-```sh
+```shell
 az login
 ```
 
 and select the subscription where you have [configured the Data API builder App Registration](#configure-server-app-registration).
 
-```sh
+```shell
 az account set --subscription <subscription name or id>
 ```
 
 then run the following command to try to authenticate against the newly created scope:
 
-```sh
+```shell
 az account get-access-token --scope api://<Application ID>/Endpoint.Access
 ```
 
@@ -107,7 +107,7 @@ It should return an error like the following:
 AADSTS65001: The user or administrator has not consented to use the application with ID '<AZ CLI Application ID GUID>' named 'Microsoft Azure CLI'. Send an interactive authorization request for this user and resource.
 ```
 
-The \<AZ CLI Application ID GUID\>, which represents AZ CLI, must be allowed to authenticate against the Data API builder Azure AD Application. To do that, search for the "Data API builder" application in the Azure Portal or go to the Azure Active Directory portal blade and select **App Registrations**. Select the "Data API builder" application and then:
+The '\<AZ CLI Application ID GUID\>', which represents AZ CLI, must be allowed to authenticate against the Data API builder Azure AD Application. To do that, search for the "Data API builder" application in the Azure Portal or go to the Azure Active Directory portal blade and select **App Registrations**. Select the "Data API builder" application and then:
 
 1. Navigate to **Expose an API** from your App Registration overview page.
    1. Under *Authorized client applications*, select **Add a client application**
@@ -176,14 +176,14 @@ To test out that authentication is working fine, you can update your configurati
 
 You can use any HTTP client now to send an authenticated request. Firstly get the token:
 
-```sh
+```shell
 az account get-access-token --scope api://<Application ID>/Endpoint.Access --query "accessToken" -o tsv
 ```
 
 then you can use the obtained access token to issue a successful authenticated request to a protected endpoint:
 
-```sh
-curl -k -r GET -H 'Authorization: Bearer ey...xA' -H 'X-MS-API-ROLE: Sample.Role' https://localhost:5001/api/Book
+```shell
+curl -k -r GET -H 'Authorization: Bearer ey...' -H 'X-MS-API-ROLE: Sample.Role' https://localhost:5001/api/Book
 ```
 
 ## Create Postman Client App Registration

docs/authentication.md

@@ -43,7 +43,7 @@ The supported providers are the following:
 
 ## Roles Selection
 
-Once a request has been authenticated via any of the available options, the roles defined in the token will be used to help determine how permission rules will be evaluated to [authorize](./authorization.md) the request. Any authenticated request will be automatically assigned to the `authenticated` system role, unless a user role is requested to be used, as described in the [Authorization](./authorization.md.md) document.
+Once a request has been authenticated via any of the available options, the roles defined in the token will be used to help determine how permission rules will be evaluated to [authorize](./authorization.md) the request. Any authenticated request will be automatically assigned to the `authenticated` system role, unless a user role is requested to be used, as described in the [Authorization](./authorization.md) document.
 
 ## Anonymous Requests
 

docs/authorization.md

@@ -15,7 +15,7 @@ There are two system roles:
 
 ### User Roles
 
-An authenticated request comes with a set of role claims that describe the requestor's role membership. When using EasyAuth authentication, the received token can be something like the following:
+An authenticated request comes with a set of role claims that describe the requestor's role membership. When using EasyAuth authentication (the default when using `StaticWebApps` as authentication mode), the received token can be something like the following:
 
 ```json
 {
@@ -33,7 +33,7 @@ An authenticated request comes with a set of role claims that describe the reque
 the roles will be used to match any defined role in the configuration file. For example, a request coming in with the aforementioned sample token will be matched with the `author` permissions if the sample `book` entity is configured like the following:
 
 ```json
-"book": {
+"Book": {
     "source": "books",
     "permissions": [
         {
@@ -80,11 +80,11 @@ A request can only be evaluated in the context of a single role. So, if the acce
 
 the desired role must be specified in the `X-MS-API-ROLE` HTTP Header.
 
-If `X-MS-API-ROLE` is not specified for an authenticated request, the request is assumed to be evaluated in the context of the `authenticated` system role.
+> ATTENTION! If `X-MS-API-ROLE` is not specified for an authenticated request, the request is assumed to be evaluated in the context of the `authenticated` system role.
 
 ## Permissions
 
-Permissions and their components,  `roles`, `actions`, `fields` and `policies`, are explained in the [configuration file](./configuration-file.md#permissions) documentation.
+Permissions and their components, `roles`, `actions`, `fields` and `policies`, are explained in the [configuration file](./configuration-file.md#permissions) documentation.
 
 There can be multiple roles defined in an entity's permissions configuration. However, a request is only evaluated in the context of a single role. The role evaluated for a request is either a system role automatically assigned by the Data API builder engine or a role manually specified in the `X-MS-API-ROLE` HTTP header.
 
@@ -141,7 +141,7 @@ For more details, see the [configuration file](./configuration-file.md#actions)
 
 ### Item level security
 
-Database policy expressions enable results to be restricted even further. Database policies translate OData expressions to query predicates executed against the database. Database policy expressions are supported for the read, update, and delete actions. See the [configuration file](./configuration-file.md#policies) documentation for a detailed explanation of database policies.
+Database policy expressions enable results to be restricted even further. Database policies translate expressions to query predicates executed against the database. Database policy expressions are supported for the read, update, and delete actions. See the [configuration file](./configuration-file.md#policies) documentation for a detailed explanation of database policies.
 
 |Action   | Database Policy Support | Details  |
 |---|:-:|---|

docs/azure-container-self-hosting.md

@@ -1,26 +1,22 @@
-# Runtime to Database Authorization
+# SESSION_CONTEXT and Row Level Security
 
-- [MsSql](#mssql)
+## SESSION_CONTEXT
 
-## MsSql
+For Azure SQL and SQL Server, Data API builder can take advantage of `SESSION_CONTEXT` to send user specified metadata to the underlying database. Such metadata is available to Data API builder by virtue of the claims present in the access token. The data sent to the database can then be used to configure an additional level of security (e.g. by configuring Security policies) to further prevent access to data in operations like SELECT, UPDATE, DELETE. The `SESSION_CONTEXT` data is available to the database for the duration of the database connection until that connection is closed. The same data can be used inside a stored procedure as well.  
 
-### SESSION_CONTEXT
+## How to read and write to `SESSION_CONTEXT`
 
-For MsSql, Data API builder uses SESSION_CONTEXT to send user specified metadata to the underlying database. Such metadata is available to Data API builder by virtue of the claims present in the access token.
-The data sent to the database can then be used to configure an additional level of security (e.g. by configuring Security policies) to further prevent access
-to data in operations like SELECT, UPDATE, DELETE. The SESSION_CONTEXT data is available to the database for the duration of the database connection until that connection is closed. The same data can be used inside a stored procedure as well.  
+Learn more about setting `SESSION_CONTEXT` data from the `sp_set_session_context` [Microsoft Learn article](https://learn.microsoft.com/sql/relational-databases/system-stored-procedures/sp-set-session-context-transact-sql).
 
-#### How to read and write to SESSION_CONTEXT
+## How to enable `SESSION_CONTEXT` in Data API builder
 
-Learn more about setting SESSION_CONTEXT data from the `sp_set_session_context` [Microsoft Learn article](https://learn.microsoft.com/sql/relational-databases/system-stored-procedures/sp-set-session-context-transact-sql).
+In the config file, the `data-source` section sub-key `options` holds database specific configuration properties. To enable `SESSION_CONTEXT`, the user needs to set the property `set-session-context` to `true`. This can be done while generating the config file via CLI at the first time or can be done later as well by setting the property manually in the config file.
 
-#### How to enable SESSION_CONTEXT in Data API builder
+## CLI command to set the `SESSION_CONTEXT`
 
-In the config file, the `data-source` section sub-key `options` holds database specific configuration properties. To enable SESSION_CONTEXT, the user needs to set the property `set-session-context` to `true` for MsSql. This can be done while generating the config file via CLI at the first time or can be done later as well by setting the property manually in the config file.
+Use the command `dab init` to generate the config file. The `--set-session-context` flag can be used to set the `SESSION_CONTEXT` property to `true`. The command looks like:
 
-##### CLI command to set the SESSION_CONTEXT
-
-```bash
+```shell
 dab init -c config.json --database-type mssql --connection-string some-connection-string --set-session-context true
 ```
 
@@ -36,9 +32,9 @@ This will generate the data-source section in config file as follows:
   }
  ```
 
-#### How and what data is sent via SESSION_CONTEXT (Example)
+## How and what data is sent via SESSION_CONTEXT 
 
-All the claims present in the EasyAuth/JWT token are sent via the SESSION_CONTEXT to the underlying database. A sample decoded EasyAuth token looks like:
+All the claims present in the EasyAuth/JWT token are sent via the `SESSION_CONTEXT` to the underlying database. A sample decoded EasyAuth token looks like:
 
 ```json
 {
@@ -94,7 +90,7 @@ All the claims present in the EasyAuth/JWT token are sent via the SESSION_CONTEX
 }
 ```
 
-All the claims present in the the token are translated into key-value pairs passed via SESSION_CONTEXT query formulated like below:
+All the claims present in the the token are translated into key-value pairs passed via `SESSION_CONTEXT` query formulated like below:
 
 ```sql
 EXEC sp_set_session_context 'aud', '<AudienceID>', @read_only = 1;
@@ -110,20 +106,19 @@ EXEC sp_set_session_context 'uti', '_sSP3AwBY0SucuqqJyjEAA', @read_only = 1;
 EXEC sp_set_session_context 'ver', '2.0', @read_only = 1;
 ```
 
-#### Example: How to use SESSION_CONTEXT to configure additional level of security (Row Level Security)
+## Example: How to use `SESSION_CONTEXT` to leverage Row Level Security (RLS)
 
-For more details about Row Level Security (RLS), please refer this [Microsoft Learn article](https://learn.microsoft.com/sql/relational-databases/security/row-level-security), but, basically RLS enables us to use group membership or execution context to control access to rows in a database table.  
+For more details about Row Level Security (RLS), please refer this [Microsoft Learn article](https://learn.microsoft.com/sql/relational-databases/security/row-level-security). 
 
 In this demonstration, we will first be creating a database table `revenues`. We will then configure a [Security Policy](https://learn.microsoft.com/sql/t-sql/statements/create-security-policy-transact-sql) which would add a FILTER PREDICATE
-to this `revenues` table. The [FILTER PREDICATE](https://learn.microsoft.com/sql/relational-databases/security/row-level-security#Description) is nothing but a table-valued function which will filter the rows accessible to operations SELECT, UPDATE, DELETE
-based on the criteria that is configured for the function.  
+to this `revenues` table. The [FILTER PREDICATE](https://learn.microsoft.com/sql/relational-databases/security/row-level-security#Description) is nothing but a table-valued function which will filter the rows accessible to operations SELECT, UPDATE, DELETE based on the criteria that is configured for the function.  
 At the end of the demonstration, we will see that only those rows are returned to the user which match the criteria of the filter predicate imposed by the security policy.  
 
-##### Laying down the ground work for SESSION_CONTEXT- SQL Queries
+### Laying down the ground work for `SESSION_CONTEXT` - SQL Queries
 
 We can execute the below SQL queries in the same order via SSMS or any other SQL client to lay the groundwork for SESSION_CONTEXT.
 
-###### Creating revenues table
+#### Creating revenues table
 
 ```sql
 CREATE TABLE revenues(
@@ -142,9 +137,9 @@ INSERT INTO revenues(id, category, revenue, username) VALUES
 (4, 'Series', 40000, 'Davide');  
 ```
 
-###### Creating function to be used as FILTER PREDICATE
+#### Creating function to be used as FILTER PREDICATE
 
-Create a function to be used as a filter predicate by the security policy to restrict access to rows in the table for SELECT, UPDATE, DELETE operations. We use the variable @username to store the value of the column revenues.username and then filter the rows accessible to the user using the filter predicate with condition: @username = SESSION_CONTEXT(N'name').
+Create a function to be used as a filter predicate by the security policy to restrict access to rows in the table for SELECT, UPDATE, DELETE operations. We use the variable @username to store the value of the column revenues.username and then filter the rows accessible to the user using the filter predicate with condition:` @username = SESSION_CONTEXT(N'name')`.
 
 ```sql
 CREATE FUNCTION dbo.revenuesPredicate(@username varchar(max))  
@@ -154,7 +149,7 @@ AS RETURN SELECT 1 AS fn_securitypredicate_result
 WHERE @username = CAST(SESSION_CONTEXT(N'name') AS varchar(max));  
 ```
 
-###### Creating SECURITY POLICY to add to the revenues table
+#### Creating SECURITY POLICY to add to the revenues table
 
 Adding a security policy which would restrict access to the rows in revenues table for SELECT, UPDATE, DELETE operations using the filter predicate dbo.revenuesPredicate.
 
@@ -164,7 +159,7 @@ ADD FILTER PREDICATE dbo.revenuesPredicate(username)
 ON dbo.revenues;  
 ```
 
-##### SESSION_CONTEXT in action
+#### SESSION_CONTEXT in action
 
 Now that we have laid the groundwork for SESSION_CONTEXT, it's time to see it in action.  
 
@@ -173,7 +168,7 @@ EXEC sp_set_session_context 'name', 'Sean'; -- setting the value of 'name' key i
 SELECT * FROM dbo.revenues;  
 ```
 
-###### Result
+#### Result
 
 Rows corresponding to `username` = 'Sean' are returned as only these rows match the criteria of the filter predicate imposed by the security policy.
 

docs/runtime-to-database-authorization.md docs/azure-sql-session-context-rls.md

@@ -90,6 +90,12 @@ make sure to replace the **VERSION-suffix** placeholder with the version you wan
 https://dataapibuilder.azureedge.net/schemas/v0.4.11-alpha/dab.draft.schema.json
 ```
 
+the **latest** version of the schema is always available at
+
+```txt
+https://dataapibuilder.azureedge.net/schemas/latest/dab.draft.schema.json 
+```
+
 ### Data Source
 
 The `data-source` element contains the information needed to connect to the backend database.
@@ -104,9 +110,10 @@ The `data-source` element contains the information needed to connect to the back
 `database-type` is a `enum string` and is used to specify what is the used backend database. Allowed values are:
 
 + `mssql`: for Azure SQL DB, Azure SQL MI and SQL Server
-+ `postgresql`: for PostgresSQL
++ `postgresql`: for PostgreSQL
 + `mysql`: for MySQL
-+ `cosmos`: for Cosmos DB
++ `cosmosdb_nosql`: for Cosmos DB NoSQL API
++ `cosmosdb_postgresql`: for Cosmos DB PostgreSQL API
 
 while `connection-string` contains the ADO.NET connection string that Data API builder will use to connect to the backend database