Update README

README.md

@@ -2,10 +2,41 @@
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-### Data API builder for Azure Databases provide modern REST and GraphQL endpoints to your Azure Databases.
+Latest version of Data API builder is  **0.1.5** also known as **M1.5**
+
+## About
+
+**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 by any platform, any language, any device. With an integrated and flexible policy engine, granular security is assured; integrated with Azure SQL DB, SQL Server, PostgreSQL, MySQL, MariaDB and Cosmos DB, gives developer an efficiency boost like it was never seen before.
 
+![Data API Builder Architecture Overview Diagram](./docs/media/data-api-builder-overview.png)
+
+## Features
+
+- Allow collections, tables and views to be accessed via REST and GraphQL
+- Support authentication via JWT and EasyAuth
+- 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
+- GraphQL 
+  - queries and mutations
+  - filtering, sorting and pagination
+  - relationship navigation
+- Easy development via dedicated CLI
+
+## Limitations 
+
+- JWT only supports AAD
+- Tables must have a primary key. The primary key must be built on a single column.
+- MySQL, MariaDB and PostgreSQL are not yet fully supported.
+
+## Known Issues
+
+List of known issues and possible workarounds, where applicable and possible, is available here: [Known Issues](./docs/known-issues.md).
+
 ## Getting Started
 
 To get started quickly with Data API builder for Azure Databases, you can use the [Getting Started](./docs/getting-started/getting-started.md) tutorial, that will help to get familiar with some basic tools and concepts while giving you a good experience on how much Data API builder for Azure Databases can make you more efficient, but removing the need to write a lot of plumbing code.

docs/authentication.md

@@ -0,0 +1,45 @@
+# Authentication
+
+Data API builder allows developers to define the authentication mechanisms they want to use to authenticate incoming requests.
+
+Authentication is not performed by Data API builder, but is delegated to one of the supported authentication providers. The supported authentication providers are:
+
+- EasyAuth
+- JWT
+
+## EasyAuth
+
+When using this provider, Data API builder will expect to EasyAuth to have authenticated the request, and to have authentication data available in the `X-MS-CLIENT-PRINCIPAL` HTTP header, as described here for App Service: [Work with user identities in Azure App Service authentication](https://docs.microsoft.com/en-us/azure/app-service/configure-authentication-user-identities) and here for Static Web Apps: [Accessing User Information](https://docs.microsoft.com/azure/static-web-apps/user-information?tabs=csharp).
+
+To use this provider you need to specify the following configuration in the `runtime.host` section of the configuration file:
+
+```json
+"authentication": {
+    "provider": "StaticWebApps"
+}
+```
+
+Using the EasyAuth provider is useful when you plan to run Data API builder in Azure, hosting it using an App Service and running it in a continer: [Run a custom container in Azure](https://docs.microsoft.com/en-us/azure/app-service/quickstart-custom-container?tabs=dotnet&pivots=container-linux-vscode).
+
+## JWT
+
+To use the JWT provider, you need to configure the `runtime.host.authentication` section by providing the needed information to verify the received JWT token:
+
+```json
+"authentication": {
+    "provider": "AzureAD",
+    "jwt": {
+        "audience": "<APP_ID>",
+        "issuer": "https://login.microsoftonline.com/<AZURE_AD_TENANT_ID>/v2.0"
+    }
+}
+```
+
+## Roles Selection
+
+Once a request has been authenticated via any of the available mechanisms, the roles defined in the claims will be used to help determine how permission rules will be applied to [authorize](./authorization.md) the request.
+
+## Anonymous Requests
+
+Requests can also be made without being authenticated. In such case the request will be automatically assigned to the `anonymous` system role so that it can be properly [authorized](./authorization.md).
+

docs/authorization.md

@@ -0,0 +1,19 @@
+# Authorization
+
+Data API builder uses a role-based authorization workflow.
+
+## Roles
+
+Roles, with the exception of the system roles described below, are not pre-defined and are inferred from the claims found in the incoming request.
+
+### System Roles
+
+There are two system roles:
+
+- `anonymous`: all non-authenticated requests will be assigned to this role
+- `authenticated`: all authenticated requests will be assigned to this role
+
+### User Roles
+
+
+##