Feature Request / Improvement
The spec and xtable-service describe different APIs, and the gap is wide enough that it changes
what a contributor should do about anything else in the file. xtable-service/src/main contains
exactly two JAX-RS annotations:
ConversionResource.java:32 @Path("/v1/conversion")
ConversionResource.java:40 @Path("/table") // @POST
There is no @GET, nothing reads the Prefer header, and there is no ExceptionMapper or
ErrorModel class anywhere in the module. So three things the spec documents do not exist:
GET /v1/conversion/table/{conversion-id}, the whole polling half of the API.Prefer: respond-async and the 202 / SubmittedConversionResponse flow.ErrorModel on 403, 503 and default. Callers get the framework's own error body.
Both the spec's info.description and spec/README.md say it is "under active development and is
subject to changes", and it is at version: 0.0.1, so this may be entirely deliberate -- a design
the service has not caught up to. That is the question, and the answer decides the work:
If the spec is a design target, the async flow and the poll endpoint are a to-do list, and the
contract is worth tightening before anyone implements it. Concretely:
- Make the job a resource.
POST /v1/conversions returning 202 with Location: /v1/conversions/{id} and Retry-After, and GET /v1/conversions/{id} returning 200 with a
status field. Polling with 202 cannot express "no such job", which is why there is no 404
today; 200 + status can, and it is what the Iceberg REST catalog and most job APIs do.
- Add the codes the current file omits:
400 for an unusable request, 404 for an unknown id,
409 for a conversion already running against the same table.
- Make
source-format and target-formats enums, target-formats minItems: 1 and
uniqueItems: true, and add request and response examples.
- Declare
securitySchemes, even if auth stays pluggable.
- Give
ErrorModel a stable application code (UNSUPPORTED_FORMAT, TABLE_NOT_FOUND) rather than
an integer that restates the HTTP status.
If the spec is meant to describe the service, the honest change is the opposite one: cut it back
to the single POST, and add the rest when it is built.
I am happy to write either as a spec change, and to split it so each piece is reviewable on its own.
I would rather not guess -- the two directions undo each other. I am not proposing to touch
xtable-service myself; this is a question about the contract.
#917 handles three inaccuracies that need fixing under either answer.
This issue was created with AI assistance.
Feature Request / Improvement
The spec and
xtable-servicedescribe different APIs, and the gap is wide enough that it changeswhat a contributor should do about anything else in the file.
xtable-service/src/maincontainsexactly two JAX-RS annotations:
There is no
@GET, nothing reads thePreferheader, and there is noExceptionMapperorErrorModelclass anywhere in the module. So three things the spec documents do not exist:GET /v1/conversion/table/{conversion-id}, the whole polling half of the API.Prefer: respond-asyncand the202/SubmittedConversionResponseflow.ErrorModelon403,503anddefault. Callers get the framework's own error body.Both the spec's
info.descriptionandspec/README.mdsay it is "under active development and issubject to changes", and it is at
version: 0.0.1, so this may be entirely deliberate -- a designthe service has not caught up to. That is the question, and the answer decides the work:
If the spec is a design target, the async flow and the poll endpoint are a to-do list, and the
contract is worth tightening before anyone implements it. Concretely:
POST /v1/conversionsreturning202withLocation: /v1/conversions/{id}andRetry-After, andGET /v1/conversions/{id}returning200with astatusfield. Polling with202cannot express "no such job", which is why there is no404today;
200+statuscan, and it is what the Iceberg REST catalog and most job APIs do.400for an unusable request,404for an unknown id,409for a conversion already running against the same table.source-formatandtarget-formatsenums,target-formatsminItems: 1anduniqueItems: true, and add request and response examples.securitySchemes, even if auth stays pluggable.ErrorModela stable application code (UNSUPPORTED_FORMAT,TABLE_NOT_FOUND) rather thanan integer that restates the HTTP status.
If the spec is meant to describe the service, the honest change is the opposite one: cut it back
to the single
POST, and add the rest when it is built.I am happy to write either as a spec change, and to split it so each piece is reviewable on its own.
I would rather not guess -- the two directions undo each other. I am not proposing to touch
xtable-servicemyself; this is a question about the contract.#917 handles three inaccuracies that need fixing under either answer.
This issue was created with AI assistance.