docs(platform): high-level API design pages (overview + per-group) (#141)

Signed-off-by: Arnob Kumar Saha <arnob@appscode.com>

Author: ArnobKumarSaha

docs/platform/api/ace-installer/overview.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-ace-installer-overview
+    name: Overview
+    parent: api-ace-installer
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# ACE Installer — Overview
+
+`/api/v1/ace-installer` (AppsCode-hosted only)
+
+Generates and manages self-host installer bundles. Token + org context; per-action authz checks.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/schema.json`, `/model.json` | Installer JSON schema / default options |
+| POST | `/generate` | Generate an installer |
+| POST | `/import` | Import an installer |
+| GET | `/installer-meta`, `/latest-version` | Installer metadata / latest ACE version |
+| GET | `/installers/` (+`/:name/`, `/:name/:id`) | List / inspect installers |
+| DELETE | `/installers/:name/:id` | Delete a generated installer |
+| POST | `/installers/:name/:id/{reconfigure,upgrade}` | Reconfigure / upgrade an installer |
+| GET | `/installers/:name/:id/versions` | List installer versions |
+| GET | `/installers/:name/:id/archives/:archiveName` | Read installer archive details |
+| GET | `/installers/:name/:id/model.json` | Installer options |
+| GET | `/deployment/marketplace/installers/:installerID/status` | Marketplace installer status |
+
+## Reference pages
+
+- [ACE installer](../ace-installer.md)

docs/platform/api/ace-upgrade/overview.md

@@ -0,0 +1,28 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-ace-upgrade-overview
+    name: Overview
+    parent: api-ace-upgrade
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# ACE Upgrade — Overview
+
+Platform and per-cluster upgrades (FluxCD-driven).
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET/POST | `/api/v1/upgrade` | Token + org; site-admin authz (view_upgrade_history / upgrade_platform) | Platform upgrade status / trigger |
+| GET | `/api/v1/upgrade/{status,history,current-version}` | Token + org; site-admin authz (view_upgrade_history) | Upgrade job status, history, current version |
+| GET/POST | `/api/v1/clusters/:owner/:cluster/upgrade` | Cluster assignment + runtime client | Imported-cluster upgrade status / trigger |
+| GET | `/api/v1/clusters/:owner/:cluster/upgrade/{history,current-version,latest-version}` | Cluster assignment + runtime client | Upgrade info |
+| GET/POST | `/api/v1/clusters/:owner/:cluster/spoke/upgrade` (+`/history`) | Cluster assignment + runtime client | Spoke-cluster upgrade status / trigger / history |
+
+## Reference pages
+
+- [Platform upgrade](../platform-upgrade.md)
+- [Cluster upgrade](../cluster-upgrade.md)

docs/platform/api/administration/overview.md

@@ -0,0 +1,70 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-administration-overview
+    name: Overview
+    parent: api-administration
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# Administration — Overview
+
+Two admin surfaces: the legacy `/admin` group (administrative-org admins) and `/accounts/admin`
+(site-admin console powering the ACE admin UI). Both admin groups require Token + org context + authz checks.
+(The site-settings routes below are a separate surface whose read endpoints are public — see that table.)
+
+## `/api/v1/admin` (administrative-org admins)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/orgs` | List all organizations |
+| GET/POST | `/users` | List / create users |
+| PATCH/DELETE | `/users/:username` | Edit / delete a user |
+| POST | `/users/:username/update`, `/users/:username/change-password` | Update profile / change password |
+| GET/POST | `/users/:username/orgs` | List / create orgs for a user |
+| GET | `/users/:uid` | Get user info by ID |
+
+## `/api/v1/accounts/admin` (site admin console)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Usage analytics dashboard |
+| GET | `/config` | Site configuration |
+| POST | `/config/test_mail` | Send a test email |
+| GET | `/monitor` | Site monitor info |
+| DELETE | `/delete/inactive-users` | Purge inactive users |
+| GET | `/users` | List users |
+| GET | `/users/deleted_accounts` | List deleted accounts |
+| POST | `/users/deleted_accounts/:id/reactivate` | Reactivate a deleted user |
+| POST | `/users/new` | Create a user |
+| POST | `/users/:userid` | Edit a user |
+| POST | `/users/:userid/delete` | Deactivate a user |
+| GET | `/orgs` | List organizations |
+| GET | `/orgs/orphaned/` | List orphaned organizations |
+| DELETE | `/orgs/orphaned/delete/:id` | Delete an orphaned org |
+| GET | `/clusters` | List all clusters |
+| GET | `/auths`, `/auths/auth-types` | List authentication sources / types |
+| POST | `/auths/new` | Create an authentication source |
+| GET/POST | `/auths/:authid`, POST `/auths/:authid/delete` | Manage an auth source |
+| GET | `/external_oauth` | List external OAuth2 sources |
+| POST | `/external_oauth/new`, `/external_oauth/:provider`, `/external_oauth/:provider/delete` | Manage external OAuth2 sources |
+
+## Site settings (misc, `/api/v1`)
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/allowed-domains` | Public | List whitelisted email domains |
+| POST/PATCH | `/allowed-domains` | Site admin authz | Add / remove a whitelisted domain |
+| GET | `/disable-registration` | Public | Get registration enabled/disabled status |
+| POST | `/disable-registration` | Site admin authz | Enable/disable new user registration |
+| GET | `/branding` | Public | Get branding (logo, app name, colors) |
+| POST | `/branding` | Org + authzCheck(edit_branding_options) | Update branding |
+
+## Reference pages
+
+- [Administrative org](../admin-org.md)
+- [Site admin console](../site-admin-console.md)
+- [Site settings](../site-settings.md)

docs/platform/api/authorization/overview.md

@@ -0,0 +1,28 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-authorization-overview
+    name: Overview
+    parent: api-authorization
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# Authorization (Roles & Permissions) — Overview
+
+Custom role management backed by the relationship-based authorization model.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/v1/authz/objects/:objectType/:objID/allowed-permissions` | Token + org | Allowed permissions on an object |
+| POST | `/api/v1/authz/objects/allowed-permissions` | Token + org | Batch allowed-permissions query |
+| GET | `/api/v1/authz/roles/available_permissions` | Token + org | List available permissions |
+| GET/POST | `/api/v1/authz/roles` | Token + org (+create_role:org) | List / create roles |
+| GET/PUT/DELETE | `/api/v1/authz/roles/:id` | authzCheck(view/edit/delete:role) | Manage a role |
+| GET | `/api/v1/authz/roles/:id/principals` | authzCheck(viewer:role) | List principals assigned to a role |
+
+## Reference pages
+
+- [Roles & permissions](../roles-permissions.md)

docs/platform/api/billing-dashboard/overview.md

@@ -0,0 +1,56 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-billing-dashboard-overview
+    name: Overview
+    parent: api-billing-dashboard
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# Billing Dashboard & Usage Reports — Overview
+
+Available on billing-enabled deployments.
+
+## Site-admin billing dashboard (`/api/v1/dashboard`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/users/` (+`/active`, `/inactive`) | Licensed users |
+| GET | `/users/:uid/clusters/` (+`/active`, `/:cid/`) | A user's clusters |
+| GET | `/users/:uid/clusters/:cid/licenses/` (+`/active`, `/:lid/`) | Licenses per cluster |
+| GET | `/users/:uid/clusters/:cid/licenses/:lid/products/` (+`/:productName/`) | Licensed products |
+| GET | `.../products/:productName/{resources,events-histories,events/,events/raw-event}` | Product resource history & audit events |
+| GET | `/clusters/:cid/licenses/active` | Active licenses for a cluster |
+| POST | `/system-outages/`, GET `/system-outages/{report,tags}` | System outage records |
+| GET | `/marketplaces/subscriptions`, `/marketplaces/settings/warnings` | Marketplace subscriptions / warnings |
+| GET/DELETE | `/marketplaces/:marketplace/:subscriptionId/` (+`/ping`, `/audit-logs`) | Inspect / revoke / ping a subscription |
+
+## User billing dashboard (`/api/v1/user/dashboard/clusters`, Token)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/active` | My active clusters |
+| GET | `/:cid/` (+`/events-count`) | Cluster info / events count |
+| GET | `/:cid/licenses/` (+`/:lid/`) | Licenses |
+| GET | `/:cid/licenses/:lid/products/:product/{events-count,events/,events/raw-event}` | License events per product |
+| GET | `/:cid/licenses/:lid/products/:product/groups/:group/resources/:resource/:rid/events-count` | Per-resource events count |
+
+## Usage reports (`/api/v1/dashboard/summary`, `/api/v1/dbaas`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/summary/generated-months` | Months with generated usage reports |
+| GET | `/summary/object-quota-history/clusters/:clusterUID/objects/:objectID` | Object quota history |
+| GET | `/summary/:year/:month/usage-report/products/kubeDb/views/*` | KubeDB usage views (objects, clusters, namespaces, GKS, contracts, quota history, cluster-mode) |
+| GET | `/summary/:year/:month/usage-report/products/{kubeStash,kubeVault,voyager}/views/{clusters,contracts}-usage-view` | Usage views per product |
+| GET | `/summary/:year/:month/download` | Download PDF usage report |
+| GET | `/dbaas/billing/reports/namespaces` (+`/clusters/:clusterID/namespaces/:namespaceName`) | DBaaS billing namespace reports |
+
+## Reference pages
+
+- [Admin dashboard](../admin-dashboard.md)
+- [User dashboard](../user-dashboard.md)
+- [Usage reports](../usage-reports.md)

docs/platform/api/chart-repositories/overview.md

@@ -0,0 +1,25 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-chart-repositories-overview
+    name: Overview
+    parent: api-chart-repositories
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# Helm Chart Repositories (public) — Overview
+
+`/api/v1/chartrepositories`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | List chart repositories |
+| GET | `/charts` | List charts |
+| GET | `/charts/:name/versions` | List versions of a chart |
+
+## Reference pages
+
+- [Chart repositories](../chart-repositories.md)

docs/platform/api/client-organizations/overview.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-client-organizations-overview
+    name: Overview
+    parent: api-client-organizations
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# Client Organizations — Overview
+
+For managed-service providers: site admins create "client orgs" and manage per-cluster user access.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/v1/user/clients` | Site-admin authz | List client organizations |
+| GET | `/api/v1/user/client/:id` | Site-admin authz | Get a client organization |
+| POST | `/api/v1/user/client/create` | authzCheck(create_client_org) | Create a client organization |
+| POST | `/api/v1/user/client/:orgname/{add-cluster,delete-cluster}` | authzCheck | Add / remove a cluster |
+| GET | `/api/v1/user/client/:orgname/status`, `/api/v1/user/client/:orgname/cluster/:cluster/status` | authzCheck | Client org / cluster status |
+| DELETE | `/api/v1/user/client/delete/:id` | authzCheck(delete_client_org) | Delete a client organization |
+| GET | `/api/v1/clusters/:owner/:cluster/permission/users` | Token + client-org | List users of a client org |
+| POST | `/api/v1/clusters/:owner/:cluster/permission/user/create` | Org-admin authz | Create an OCM user for a client org |
+| POST | `/api/v1/clusters/:owner/:cluster/permission/user/:id` | Org-admin authz | Get client-org user info |
+| GET | `/api/v1/clusters/:owner/:cluster/permission/user/:id/kubeconfig` | Org-admin authz | Kubeconfig for a client-org user |
+| POST | `/api/v1/clusters/:owner/:cluster/permission/user/:id/{remove,update}` | Org-admin authz | Manage permissions |
+| DELETE | `/api/v1/clusters/:owner/:cluster/permission/user/:id/delete` | Org-admin authz | Delete the OCM user |
+
+## Reference pages
+
+- [Management](../management.md)
+- [Cluster user permissions](../cluster-user-permissions.md)

docs/platform/api/cloud-providers/overview.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-cloud-providers-overview
+    name: Overview
+    parent: api-cloud-providers
+    weight: 5
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+---
+
+# Cloud Providers — Overview
+
+`/api/v1/clouds`
+
+Discovery APIs used by the cluster-provisioning wizard. Provider routes require Token + stored
+cloud credentials.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | List supported cloud providers (public) |
+| POST | `/:owner/:provider/cluster` | Provision a cluster on a provider |
+| GET | `/:owner/providers/gke/projects` (+ per-project `clusters`, `clusters/:cluster`; per-region under `projects/:project/regions/:region`: `kubernetesversions`, `vms`) | GKE discovery |
+| GET | `/:owner/providers/aks/{regions,resourcegroups}` (+ per-region `vms`/`kubernetesversions`, per-RG `clusters` and `clusters/:cluster`) | AKS discovery |
+| GET | `/:owner/providers/eks/regions` (+ per-region `kubernetesversions`, `vms`, `clusters`, `clusters/:cluster`) | EKS discovery |
+| GET | `/:owner/providers/digitalocean/clusters` (+`/:id`) | DigitalOcean discovery |
+| GET | `/:owner/providers/linode/clusters` (+`/:id`) | Linode discovery |
+| GET | `/:owner/providers/rancher/clusters/` (+`/:id`) | Rancher-managed cluster discovery |
+| GET | `/:owner/providers/hetzner/{servers,kubernetesversions,regions}` (+ per-region `servers`) | Hetzner discovery |
+| GET | `/:owner/providers/kubevirt/kubernetesversions` | KubeVirt versions |
+
+## Reference pages
+
+- [Cloud providers](../cloud-providers.md)