rahulsmahadev commented on code in PR #17727:
URL: https://github.com/apache/iceberg/pull/17727#discussion_r4458226090
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -25,9 +25,70 @@ info:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 0.0.1
- description:
+ description: |
Defines the specification for the first version of the REST Catalog API.
Implementations should ideally support all Iceberg table spec versions.
+
+ ## Client Identification
+
+ Clients SHOULD identify themselves to the catalog with the standard HTTP
+ `User-Agent` header (RFC 9110, Section 10.1.5). A consistent, parseable
+ format gives catalog operators usable telemetry for observability,
+ debugging, and support across the many engines and libraries that speak
+ this protocol.
+
+ The header is a whitespace-separated list of `product/version` tokens,
+ optionally followed by a parenthesized comment:
+
+ - When the header is sent, the token of the Iceberg client library MUST be
+ present, for example `iceberg-java`, `pyiceberg`, `iceberg-rust`,
+ `iceberg-go`, or `iceberg-cpp`. This list is illustrative, not
+ exhaustive: any other Iceberg library, or a proprietary or custom
+ implementation, uses its own descriptive product token.
+ - Product tokens SHOULD be ordered from the outermost component to the
+ innermost, so the most specific caller appears first: the engine or
+ application, then any integration or connector, then the Iceberg
+ library. The library token is therefore the last product token, which
+ lets a server identify the library and its version whatever other
+ tokens come before it.
+ - The optional comment carries lower-value context such as build
+ identifiers, the HTTP library, the language runtime, or the operating
+ system. These items SHOULD be grouped into a single comment after all
+ product tokens and separated by `; `, for example
+ `(jvm 17.0.9; ubuntu 26.04)` or
+ `(cpython 3.11.4; urllib3 2.2.1; macos 15.1)`. The comment is free-form:
+ servers SHOULD treat it as opaque and MUST NOT depend on its contents.
+
+ Examples:
+
+ - `pyiceberg/0.11.0 (cpython 3.11.4)`: a client library used directly.
+ - `Trino/438 iceberg-java/1.9.0 (jvm 17.0.9)`: an engine embedding the
+ Iceberg Java library.
+ - `Trino/438 iceberg-java/1.9.0 (jvm 17.0.9; ubuntu 26.04)`: the same
+ engine reporting both the language runtime and the operating system.
+ - `Spark/4.0.0 iceberg-spark/1.9.0 iceberg-java/1.9.0 (scala 2.13.16)`: an
+ engine with a connector layer on top of the library.
+
+ Client identification is advisory:
+
+ - Servers SHOULD NOT reject a request only because the header is absent,
+ incomplete, or malformed. Clients that do not send it remain fully
+ functional.
+ - The value is client-asserted and can be spoofed, so servers MUST NOT use
+ it for authentication or authorization.
+ - It is not a capability negotiation mechanism. Clients MUST NOT use it to
+ advertise the protocol features they support, and servers MUST NOT infer
+ from it which features a client supports. Servers advertise the
+ endpoints they support in the `endpoints` field of the config response.
+ - Servers MAY refuse specific operations when the header identifies a
+ client version known to be incompatible or unsafe, for example a library
+ version known to emit corrupt statistics. This applies only to a header
+ that names such a version. It is not an exception to the first rule: a
+ header that is absent, incomplete, or malformed is still not a reason to
+ refuse a request. A server that refuses SHOULD return the standard error
+ response with status 400 and a message that names the refused version.
Review Comment:
manuzhang asked which status code a refusing server should return
(https://github.com/apache/iceberg/pull/17727#discussion_r4290683598). 400 is
the standard client-error response. The Java client raises it as a
BadRequestException with the server's message and doesn't retry it, so naming
the refused version tells the user what to upgrade. Other codes send the wrong
signal: 403 reads as a permissions problem, and this header must not be used
for authorization; 409 is a commit conflict, which the Java client retries.
It's a SHOULD, so a server can still pick a different code.
--
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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
