docs(api): the Iceberg REST catalog endpoints are served at /v1/config and /v1/namespaces, not under /v1/iceberg by spiceemma · Pull Request #2334 · spiceai/docs

spiceemma · 2026-10-09T08:12:45Z

Summary

The HTTP API reference lists the Iceberg REST catalog endpoints under /v1/iceberg/ (/v1/iceberg/config, /v1/iceberg/namespaces, and so on). The runtime has never served them there. The router serves them at /v1/config, /v1/namespaces, /v1/namespaces/{namespace}, /v1/namespaces/{namespace}/tables, and /v1/namespaces/{namespace}/tables/{table}, which are the paths the Iceberg REST spec defines. The wrong paths came from the utoipa::path annotations that generate the OpenAPI spec. spiceai/spiceai#14588 corrected those annotations on trunk.

This PR corrects the path on each Iceberg API page in website/docs/ and in every versioned copy (1.5.x through 2.3.x), and the path keys in website/public/openapi.json. For each .api.mdx page, the path= prop and the encoded api: front-matter field change, including the request URL inside api: that the page's code samples use (fc228cb fixes that URL in the versioned copies). The Generate API Docs workflow then regenerated website/docs/api/HTTP/ from the corrected openapi.json and pushed f07235c. Its changes to the Iceberg pages are only a different compressed encoding of the same api: field. It also adds the POST /v1/datasets/{name}/cdc page, which openapi.json already described (served at crates/runtime/src/http/routes.rs:409 on trunk, and documented in features/cdc/debezium-ingest.md), and it re-encodes or reformats several other pages with no content change.

For vNext only, the GET /v1/config response example now lists the endpoints in the form trunk returns since #14588 (GET /v1/{prefix}/namespaces, ...). The versioned examples are unchanged, because they show what those releases return (see the run below).

The other #14588 behavior changes (an accelerated or non-Iceberg table refused with an error, a JSON 404 body, the namespace response shape) are not in this PR. They belong to the next openapi.json sync after spiceai/spiceai regenerates .schema/openapi.json, which still carries the /v1/iceberg/ annotations as of the trunk SHA below.

Source PRs

fix(iceberg): Iceberg REST clients read the real table or get an error, never an empty one spiceai#14588: fix(iceberg): Iceberg REST clients read the real table or get an error, never an empty one

Reproduction

Doc said (website/docs/api/HTTP/get-config.api.mdx, and the same in every versioned copy):

  path={"/v1/iceberg/config"}

Code says, at every release tag the versioned docs map to, and on trunk (routes.rs):

v1.5.2:  .route("/v1/config", get(v1::iceberg::get_config))
v1.6.1:  .route("/v1/config", get(v1::iceberg::get_config))
v1.7.3:  .route("/v1/config", get(v1::iceberg::get_config))
v1.8.3:  .route("/v1/config", get(v1::iceberg::get_config))
v1.9.2:  .route("/v1/config", get(v1::iceberg::get_config))
v1.10.4: .route("/v1/config", get(v1::iceberg::get_config))
v1.11.6: .route("/v1/config", get(v1::iceberg::get_config))
v2.0.0:  .route("/v1/config", get(v1::iceberg::get_config))
v2.1.0:  .route("/v1/config", get(v1::iceberg::get_config))
v2.2.0:  .route("/v1/config", get(v1::iceberg::get_config))
v2.3.2:  .route("/v1/config", get(v1::iceberg::get_config))
origin/trunk:crates/runtime/src/http/routes.rs:434:        .route("/v1/config", get(v1::iceberg::get_config))
origin/trunk:crates/runtime/src/http/routes.rs:435:        .route("/v1/namespaces", get(v1::iceberg::get_namespaces))

At v2.3.2 the annotation disagreed with the route (crates/runtime/src/http/v1/iceberg/mod.rs:40: path = "/v1/iceberg/config"). On trunk it is crates/runtime/src/http/v1/iceberg/mod.rs:41: path = "/v1/config".

Reproduced on released spiced v2.3.2 (release) with one file: CSV dataset:

/v1/iceberg/config -> [HTTP 404]
/v1/config -> {"overrides": {}, "defaults": {}, "endpoints": ["GET /v1/iceberg/namespaces", "HEAD /v1/iceberg/namespaces/{namespace}", ...]} [HTTP 200]
/v1/iceberg/namespaces -> [HTTP 404]
/v1/namespaces -> {"namespaces":[["spice"]]} [HTTP 200]
/v1/namespaces/spice/tables -> {"identifiers":[]} [HTTP 200]
/v1/iceberg/namespaces/spice/tables -> [HTTP 404]

The v2.3.2 /v1/config response itself lists /v1/iceberg/... endpoints, so the versioned response examples are left as they are.

Verification

Trunk SHA: 8a1e2a4c706d8f8e0718c02e146d19aceb997c83. The trunk /v1/config example comes from CONFIG_RESPONSE in iceberg/mod.rs.
Propagation: git grep -c 'path={"/v1/iceberg' -- website returns 0 files after the change; path={"/v1/config" or path={"/v1/namespaces... now appears in 56 pages (7 in website/docs/, 7 in each of 2.0.x–2.3.x, 3 in each of 1.5.x–1.11.x).
Flip-flop guard: gh pr list --repo spiceai/docs --state all --search "iceberg in:title" and --search "/v1/config" return no earlier PR that changed these paths.
An earlier version of this body said a local gen-api-docs all run left tracked files unchanged. That run proved nothing: the generator skips pages that already exist, which is why the workflow empties the directory first. Decoding the api: field before and after f07235c shows the same object on every changed page outside the Iceberg set. On the Iceberg pages, the only difference was the request URL (postman.url.path still held iceberg). The first commit missed that field, and fc228cb fixes it in the versioned copies. After fc228cb, decoding every api: field under website/docs/ and website/versioned_docs/ finds no /v1/iceberg request path or URL.

Test plan

cd website && npm run build at 7e2dc81: [SUCCESS] Generated static files in "build". exit=0 (no broken links or undefined tags)
Schema Bot regeneration (f07235c) reviewed: Iceberg pages carry the same api: object, plus the new CDC page
Paths reproduced on v2.3.2 (output in the Reproduction section above)

…g and /v1/namespaces, not under /v1/iceberg

github-actions · 2026-10-09T08:12:54Z

✅ Pull with Spice Passed

Passing checks:

✅ Title meets minimum length requirement (10 characters)
✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
✅ No banned labels detected
✅ Has at least one assignee: spiceemma

github-actions · 2026-10-09T08:12:54Z

🔍 Pull with Spice Failed

Passing checks:

✅ Title meets minimum length requirement (10 characters)
✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
✅ No banned labels detected

Failed checks:

❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

Copilot

🟢 Approved

The documented paths, encoded metadata, OpenAPI keys, and current response example consistently match the runtime routes.

0 open findings

What changed in this PR

Corrects Iceberg REST catalog endpoint documentation to match the runtime routes across current and versioned API references.

Changes:

Replaces /v1/iceberg endpoint prefixes in 56 generated API pages.
Updates OpenAPI paths and the current /v1/config response example.

File	Description
`website/public/openapi.json`	Corrects OpenAPI paths and current config example.
`website/docs/api/HTTP/list-tables.api.mdx`	Corrects the list-tables path.
`website/docs/api/HTTP/head-table.api.mdx`	Corrects the table-check path.
`website/docs/api/HTTP/head-namespace.api.mdx`	Corrects the namespace-check path.
`website/docs/api/HTTP/get-table.api.mdx`	Corrects the get-table path.
`website/docs/api/HTTP/get-namespace.api.mdx`	Corrects the get-namespace path.
`website/docs/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the list-namespaces path.
`website/docs/api/HTTP/get-config.api.mdx`	Corrects the config path and metadata.
`website/docs/api/HTTP/get-config.StatusCodes.json`	Updates the current config example.
`website/versioned_docs/version-2.3.x/api/HTTP/list-tables.api.mdx`	Corrects the versioned list-tables path.
`website/versioned_docs/version-2.3.x/api/HTTP/head-table.api.mdx`	Corrects the versioned table-check path.
`website/versioned_docs/version-2.3.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-2.3.x/api/HTTP/get-table.api.mdx`	Corrects the versioned get-table path.
`website/versioned_docs/version-2.3.x/api/HTTP/get-namespace.api.mdx`	Corrects the versioned get-namespace path.
`website/versioned_docs/version-2.3.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-2.3.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-2.2.x/api/HTTP/list-tables.api.mdx`	Corrects the versioned list-tables path.
`website/versioned_docs/version-2.2.x/api/HTTP/head-table.api.mdx`	Corrects the versioned table-check path.
`website/versioned_docs/version-2.2.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-2.2.x/api/HTTP/get-table.api.mdx`	Corrects the versioned get-table path.
`website/versioned_docs/version-2.2.x/api/HTTP/get-namespace.api.mdx`	Corrects the versioned get-namespace path.
`website/versioned_docs/version-2.2.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-2.2.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-2.1.x/api/HTTP/list-tables.api.mdx`	Corrects the versioned list-tables path.
`website/versioned_docs/version-2.1.x/api/HTTP/head-table.api.mdx`	Corrects the versioned table-check path.
`website/versioned_docs/version-2.1.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-2.1.x/api/HTTP/get-table.api.mdx`	Corrects the versioned get-table path.
`website/versioned_docs/version-2.1.x/api/HTTP/get-namespace.api.mdx`	Corrects the versioned get-namespace path.
`website/versioned_docs/version-2.1.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-2.1.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-2.0.x/api/HTTP/list-tables.api.mdx`	Corrects the versioned list-tables path.
`website/versioned_docs/version-2.0.x/api/HTTP/head-table.api.mdx`	Corrects the versioned table-check path.
`website/versioned_docs/version-2.0.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-2.0.x/api/HTTP/get-table.api.mdx`	Corrects the versioned get-table path.
`website/versioned_docs/version-2.0.x/api/HTTP/get-namespace.api.mdx`	Corrects the versioned get-namespace path.
`website/versioned_docs/version-2.0.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-2.0.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-1.11.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-1.11.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-1.11.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-1.10.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-1.10.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-1.10.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-1.9.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-1.9.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-1.9.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-1.8.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-1.8.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-1.8.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-1.7.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-1.7.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-1.7.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-1.6.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-1.6.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-1.6.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.
`website/versioned_docs/version-1.5.x/api/HTTP/head-namespace.api.mdx`	Corrects the versioned namespace-check path.
`website/versioned_docs/version-1.5.x/api/HTTP/get-iceberg-namespaces.api.mdx`	Corrects the versioned list-namespaces path.
`website/versioned_docs/version-1.5.x/api/HTTP/get-config.api.mdx`	Corrects the versioned config path.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

github-actions · 2026-10-09T08:17:40Z

🚀 deployed to https://3fcbb0ee.spiceai-org-website.pages.dev

…d Iceberg API pages

Copilot

🟡 Changes recommended

The diff includes generated CDC and other API documentation changes that the description explicitly places outside this PR’s scope.

1 open finding

Remove out-of-scope post-dataset-cdc pages and sidebar entry · New

🧠 Review effort: Balanced

Copilot

🟡 Changes recommended

The CDC documentation does not warn that a timed-out batch may still apply, making retries unsafe for append-only datasets.

3 open findings

Remove out-of-scope post-dataset-cdc pages and sidebar entry
Document indeterminate outcomes after apply timeouts · New
Complete the front-matter description · New

🧠 Review effort: Balanced

github-actions · 2026-10-09T08:25:44Z

🚀 deployed to https://f59e1e19.spiceai-org-website.pages.dev

Copilot

🟢 Approved

The corrected visible and encoded paths match the runtime routes across all documented versions.

0 open findings

3 resolved since last review

Remove out-of-scope post-dataset-cdc pages and sidebar entry
Complete the front-matter description
Document indeterminate outcomes after apply timeouts

🧠 Review effort: Balanced

docs(api): the Iceberg REST catalog endpoints are served at /v1/confi…

7e2dc81

…g and /v1/namespaces, not under /v1/iceberg

spiceemma requested a review from a team as a code owner October 9, 2026 08:12

Copilot AI balanced review requested due to automatic review settings October 9, 2026 08:12

spiceemma added area/docs kind/bug labels Oct 9, 2026

spiceemma self-assigned this Oct 9, 2026

spiceemma added area/config and removed area/config labels Oct 9, 2026

Copilot started reviewing on behalf of spiceemma October 9, 2026 08:13 View session

chore: update API docs

f07235c

Copilot AI previously approved these changes Oct 9, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 9, 2026 08:15

Copilot AI dismissed their stale review, a newer Copilot review was requested October 9, 2026 08:15

Copilot started reviewing on behalf of spiceemma October 9, 2026 08:15 View session

github-actions Bot deployed to preview October 9, 2026 08:17 View deployment

docs(api): drop /iceberg from the request URL encoded in the versione…

fc228cb

…d Iceberg API pages

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Comment thread website/docs/api/HTTP/sidebar.ts

Copilot AI balanced review requested due to automatic review settings October 9, 2026 08:20

Copilot started reviewing on behalf of spiceemma October 9, 2026 08:21 View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Comment thread website/docs/api/HTTP/post-dataset-cdc.StatusCodes.json

Comment thread website/docs/api/HTTP/post-dataset-cdc.api.mdx

github-actions Bot deployed to preview October 9, 2026 08:25 View deployment

spiceemma mentioned this pull request Oct 9, 2026

docs(api): POST /v1/datasets/{name}/cdc OpenAPI description truncates, and its 504 may leave the batch's outcome indeterminate spiceai/spiceai#14943

Open

spiceemma requested a balanced review from Copilot October 9, 2026 09:08

Copilot started reviewing on behalf of spiceemma October 9, 2026 09:09 View session

Copilot AI approved these changes Oct 9, 2026

View reviewed changes

lukekim approved these changes Oct 9, 2026

View reviewed changes

lukekim merged commit 01af077 into trunk Oct 9, 2026
11 checks passed

lukekim deleted the emma/docs-iceberg-rest-paths branch October 9, 2026 16:34

Navigation Menu

Repository navigation

docs(api): the Iceberg REST catalog endpoints are served at /v1/config and /v1/namespaces, not under /v1/iceberg - #2334

docs(api): the Iceberg REST catalog endpoints are served at /v1/config and /v1/namespaces, not under /v1/iceberg#2334
lukekim merged 3 commits into
trunkfrom
emma/docs-iceberg-rest-paths

spiceemma commented Oct 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

spiceemma commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Source PRs

Reproduction

Verification

Test plan

Uh oh!

github-actions Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull with Spice Passed

Passing checks:

Uh oh!

github-actions Bot commented Oct 9, 2026

🔍 Pull with Spice Failed

Passing checks:

Failed checks:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approved

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approved

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

spiceemma commented Oct 9, 2026 •

edited

Loading

github-actions Bot commented Oct 9, 2026 •

edited

Loading