slachiewicz opened a new issue, #918:
URL: https://github.com/apache/incubator-xtable/issues/918
## 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.*
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
