From 4ced2d83eab41f9b237d8f2cb04aa6e7094d9d9f Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Sun, 21 Jun 2026 15:50:08 +0800
Subject: [PATCH] docs(service-datasource): list REST routes + Studio/Setup-nav
 integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README mentioned "REST routes under /api/v1/datasources" but didn't
enumerate them, and predated the Studio integration. Add:
- a REST routes section (lifecycle + drivers catalog + by-name test + GET :name
  detail + introspection/sync routes), with the credential-split note;
- a Studio integration section: datasource is managed through the metadata-admin
  engine (Setup → Integrations → Datasources), runtime records persist to
  sys_metadata and rehydrate on restart.

Reflects #2083 (drivers), #2085 (remote-tables/object-draft/by-name test),
#2086 (GET :name), #2091 (Setup nav), #2096 (persistence).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../services/service-datasource/README.md     | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/services/service-datasource/README.md b/packages/services/service-datasource/README.md
index 364ff71f45..dcab541719 100644
--- a/packages/services/service-datasource/README.md
+++ b/packages/services/service-datasource/README.md
@@ -33,6 +33,40 @@ layered on by a private host **without forking**.
 
 The runtime admin owns only the `origin: 'runtime'` lifecycle.
 
+## REST routes
+
+Mounted under `/api/v1/datasources` by `registerDatasourceAdminRoutes` (lifecycle
++ introspection) and the federation routes by the external service. Every route
+degrades gracefully (`503` / "unavailable") when its service isn't wired.
+
+**Lifecycle & connection**
+- `GET    /datasources` — list (code + runtime, with provenance/health)
+- `GET    /datasources/drivers` — driver catalog + per-driver JSON-Schema `configSchema` (drives the Studio connection form)
+- `GET    /datasources/:name` — one datasource's detail, **credential-stripped** (`config` + `hasSecret`)
+- `POST   /datasources` — create a runtime datasource
+- `PATCH  /datasources/:name` — update a runtime datasource
+- `DELETE /datasources/:name` — remove a runtime datasource (blocked while objects are bound)
+- `POST   /datasources/test` — probe an unsaved draft (inline body)
+- `POST   /datasources/:name/test` — probe a **saved** datasource by name (backs the `test_connection` action)
+
+**Introspection / sync (read-only)**
+- `GET    /datasources/:name/remote-tables` — list remote tables
+- `POST   /datasources/:name/object-draft` — generate an object definition draft for one table (no persistence)
+- federation import/validate/refresh routes under `/datasources/:name/external/*` (ADR-0015)
+
+Credentials never travel in `config`: a `format:'password'` field is split into
+the top-level `secret` on write (encrypted to `sys_secret`), and reads never
+echo it (`hasSecret` only).
+
+## Studio integration
+
+`datasource` is a metadata type, so it is administered through the generic
+metadata-admin engine (not a bespoke page): the `DatasourceAdminServicePlugin`
+contributes a **Datasources** entry to the Setup app's `group_integrations` nav
+slot (→ the engine route `…/component/metadata/resource?type=datasource`), where
+the list/create/edit/test/**sync objects**/delete UI lives. Runtime records are
+persisted to `sys_metadata` and restored (pools rehydrated) on restart.
+
 ## Exports
 
 - Federation: `ExternalDatasourceService`, `ExternalDatasourceServicePlugin`.