Basic Server Access Control, Securables and Client API

Author: jaceklaskowski

docs/basic-server-access-control/index.md

@@ -12,9 +12,24 @@
 * The root of the hierarchy is a catalog.
 * There is a new concept of a metastore, which is primarily a resource to assign server-level privileges with.
 
-??? note
+!!! note "Permissions and Privilege Assignments"
+    **Permissions** and **Privilege Assignments** are synonyms.
+
+??? note "Commit"
     Basic Server Access Control is available since [this commit]({{ uc.commit }}/f9a9bf1f84cb4c7fa03ecb569ae19f306a7cd85b).
 
+## Securables
+
+Unity Catalog supports the following types of securables to apply (_create_) permissions to:
+
+1. `catalog`
+1. `function`
+1. `metastore`
+1. `registered_model`
+1. `schema`
+1. `table`
+1. `volume`
+
 ## Privileges
 
 The initial set of privileges are as follows:
@@ -35,14 +50,14 @@ Privilege | Description
 
 ## Unity Catalog CLI
 
-The CLI interface provides a new `permission` command.
+The CLI interface provides a new [permission](../cli/PermissionCli.md) command.
 
 ``` bash
 ./bin/uc permission create \
   --securable_type catalog \
   --name mycatalog \
   --principal [email protected] \
-  --privilege "CREATE CATALOG`
+  --privilege "CREATE CATALOG"
 ```
 
 ``` bash

docs/cli/PermissionCli.md

@@ -9,21 +9,6 @@ Valid sub-commands for permission are: get, create, delete
 For detailed help on permission sub-commands, use bin/uc permission <sub-command> --help
 ```
 
-!!! note
-    **Permissions** and **Privilege Assignments** are synonyms.
-
-## Securable Types
-
-There are the following types of the securables in Unity Catalog:
-
-1. `catalog`
-1. `function`
-1. `metastore`
-1. `registered_model`
-1. `schema`
-1. `table`
-1. `volume`
-
 ## Handle Command Line { #handle }
 
 ```java
@@ -34,13 +19,13 @@ void handle(
 
 `handle` handles the given `cmd`.
 
-`handle` creates a `GrantsApi` (with the given [ApiClient](../client/ApiClient.md)).
+`handle` creates a [GrantsApi](../client/GrantsApi.md) (with the given [ApiClient](../client/ApiClient.md)).
 
 Subcommand | Handler | API Handlers
 -|-|-
- `create` | [updatePermission](#updatePermission) | `GrantsApi`
- `delete` | [updatePermission](#updatePermission) | `GrantsApi`
- `get` | [getPermission](#getPermission) | `GrantsApi`
+ `create` | [updatePermission](#updatePermission) | [GrantsApi](../client/GrantsApi.md)
+ `delete` | [updatePermission](#updatePermission) | [GrantsApi](../client/GrantsApi.md)
+ `get` | [getPermission](#getPermission) | [GrantsApi](../client/GrantsApi.md)
 
 ---
 
@@ -84,4 +69,4 @@ Optional Params:
 * `name`
 * `principal`
 
-`getPermission` requests the `GrantsApi` for the privilege assignments of the given `name` (of `securable_type` type).
+`getPermission` requests the [GrantsApi](../client/GrantsApi.md) for the privilege assignments of the given `name` (of `securable_type` type).

docs/client/ApiClient.md

@@ -1,11 +1,6 @@
 # ApiClient
 
-`ApiClient` is an API client of [Unity Catalog Localhost Reference Server](../server/index.md).
-
-??? note "OpenAPI Generator"
-    `ApiClient` was auto-generated using [OpenAPI Generator]({{ openapi.home }}) based on Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml).
-
-    [sbt-openapi-generator]({{ openapi.github }}/sbt-openapi-generator) 7.5.0 is used in the `client` sbt module of the `unitycatalog` project.
+`ApiClient` is an API client of the [Unity Catalog Server](../server/index.md).
 
 `ApiClient` uses `http://localhost:8080/api/2.1/unity-catalog` as the [default base URI](#getDefaultBaseUri) (unless [overriden](#updateBaseUri)).
 

docs/client/GrantsApi.md

@@ -0,0 +1,3 @@
+# GrantsApi
+
+`GrantsApi` is...FIXME

docs/client/index.md

@@ -1 +1,11 @@
-# Unity Catalog's Client API
+# Client API
+
+Client API uses Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml) to generate the required classes (using [OpenAPI Generator](#openapi-generator)) to communicate with [Unity Catalog Server](../server/index.md).
+
+The main communication client is [ApiClient](ApiClient.md).
+
+## OpenAPI Generator
+
+All the classes in `io.unitycatalog.client.api` Java package (e.g., [ApiClient](ApiClient.md), [GrantsApi](GrantsApi.md)) are auto-generated using [OpenAPI Generator]({{ openapi.home }}) based on Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml).
+
+[sbt-openapi-generator]({{ openapi.github }}/sbt-openapi-generator) 7.5.0 is used in the `client` sbt module of the `unitycatalog` project.