flyrain commented on code in PR #9695:
URL: https://github.com/apache/iceberg/pull/9695#discussion_r1747713358
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -541,6 +541,264 @@ paths:
5XX:
$ref: '#/components/responses/ServerErrorResponse'
+ /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan:
+ parameters:
+ - $ref: '#/components/parameters/prefix'
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ post:
+ tags:
+ - Catalog API
+ summary: Submit a scan for planning
+ description: >
+ Submits a scan for server-side planning.
+
+
+ Point-in-time scans are planned by passing snapshot-id to identify the
+ table snapshot to scan. Incremental scans are planned by passing both
+ start-snapshot-id and end-snapshot-id. Requests that include both point
+ in time config properties and incremental config properties are
+ invalid. If the request does not include either incremental or
+ point-in-time config properties, scan planning should produce a
+ point-in-time scan of the latest snapshot in the table's main branch.
+
+
+ Responses must include a valid status
+
+ - When "completed" the planning operation has produced plan tasks and
+ file scan tasks that must be returned in the response (not fetched
+ later by calling fetchPlanningResult)
+
+ - When "submitted" the response must include a plan-id used to poll
+ fetchPlanningResult to fetch the planning result when it is ready
+
+ - When "failed" the response must be a valid error response
+
+ - Status "cancelled" is not a valid status from this endpoint
Review Comment:
Nit: Could we separate this into its own paragraph? It might be confusing
for quick readers if it's mixed with other valid statuses. For clarity, it
could look something like this:
```
Responses must include a valid status as the following shows, please note
that `cancelled` is not valid status
- "completed":
- "submitted":
- "failed":
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For additional commands, e-mail: issues-h...@iceberg.apache.org
