[rest] Add database branch and tag APIs

docs/docs/concepts/rest/index.md

@@ -74,6 +74,8 @@ Choose the authentication guide for your service:
 ## API References
 
 - [REST Catalog API](./rest-api): the OpenAPI contract for catalog operations.
+- [Database Branches and Tags](./database-versioning): experimental reference management, database-name selectors, and
+  the server MVP design using existing table branches and tags.
 - [REST Management API](./management-api): permissions, row filters, column masking, and the
   corresponding Spark SQL procedures.
 

docs/docs/concepts/rest/rest-api.md

@@ -52,14 +52,20 @@ payloads, and error responses are defined in the OpenAPI specification.
 | Commits and snapshots | Commit, roll back, and inspect table versions. | Table-scoped `commit`, `rollback`, `rollback-schema`, `snapshot`, and `snapshots`. |
 | Data access | Request storage credentials and authorize a query. | Table-scoped `token` and `auth`. |
 | Partitions | List, create, drop, and mark partitions done. | Table-scoped `partitions`. |
-| Branches and tags | Manage named histories and retained snapshots. | Table-scoped `branches` and `tags`. |
+| Table branches and tags | Manage named histories and retained snapshots. | Table-scoped `branches` and `tags`. |
+| Database branches and tags | List, get, create, delete, and merge references. | Database-scoped `trees` and `trees/{name}/merge`. |
 | Consumers | List and reset streaming consumer progress. | Table-scoped `consumers`. |
 | Views and functions | Manage reusable SQL and function definitions. | Database- and catalog-scoped `views` and `functions`. |
 
 In this table, **table-scoped** means
 `/v1/{prefix}/databases/{database}/tables/{table}`. Catalog-wide listing and detail-listing
 endpoints are described in the specification alongside their database-scoped counterparts.
 
+See [Database Branches and Tags](./database-versioning) for reference-management examples, merge
+modes, and the server MVP design. Supported table operations select a reference with a database
+name such as `training$branch_experiment` or `training$tag_train_v1`. The existing table paths,
+request/response structures and Java methods carry the full database name.
+
 ## Partition Compatibility
 
 Partition options use the existing `POST .../partitions` request. `partitionOptions` follows the

docs/docs/program-api/rest-api.mdx

@@ -36,6 +36,8 @@ metadata requests without bringing in the full table read/write bundle.
 | Load a `Table` and read or write rows | [Java API](java-api) with a REST catalog |
 | Implement an HTTP client or catalog server | [REST API specification](../concepts/rest/rest-api) |
 | Administrative endpoints | [Management API](../concepts/rest/management-api) |
+| Database branch/tag management | [Database Branches and Tags](../concepts/rest/database-versioning#java-management-usage) |
+| Tables within a database branch/tag | [Database-name reference selectors](../concepts/rest/database-versioning#java-table-usage) |
 
 ## Dependency
 

docs/scripts/validate-rest-openapi.js

@@ -225,6 +225,19 @@ function requireExactEnum(contract, schemaName, expectedValues) {
 
 function validateCatalogOpenApi() {
   const contract = validateCommon('rest-catalog-open-api.yaml');
+  contract.checkSpec(
+    !Object.keys(contract.spec.paths).some((path) => /\/trees\/\{[^}]+\}\/(tables|table-details)/.test(path)),
+    'Database reference access must reuse ordinary table paths',
+  );
+  const databaseParameter = contract.spec.components.parameters.Database;
+  contract.checkSpec(
+    databaseParameter.examples.branch.value === 'training$branch_experiment' &&
+      databaseParameter.examples.tag.value === 'training$tag_train_v1',
+    'Database reference examples must use the reserved branch and tag suffixes',
+  );
+  ['getDatabase', 'listTables', 'getTable', 'commitTable', 'getSchema', 'listSchemas'].forEach(
+    (operationId) => contract.requireResponses(operationId, ['404', '409', '501']),
+  );
   [
     'getConfig',
     'createDatabase',

docs/sidebars.js

@@ -44,6 +44,7 @@ const sidebars = {
           "concepts/rest/tables",
           "concepts/rest/pvfs",
           "concepts/rest/rest-api",
+          "concepts/rest/database-versioning",
           "concepts/rest/management-api"
         ]
       },