rahulsmahadev commented on code in PR #17727:
URL: https://github.com/apache/iceberg/pull/17727#discussion_r4458223176
##########
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
Review Comment:
Right, released clients don't send it. Today the Java client only sets a
User-Agent when `rest.client.user-agent` is configured, so servers see the
Apache HttpClient default (they can still identify old Java clients from the
`X-Client-Version` header). The spec can't change what's already shipped, which
is why the advisory rules say servers SHOULD NOT reject a request whose header
is absent, incomplete, or malformed. The MUST is for clients that follow this
format from now on, so a server can always rely on the library token being
there. With a SHOULD, it couldn't rely on it even for new clients. This is also
the wording the vote passed on. The client changes that add the token (Java,
Python, Go, Rust) are ready and will go out once this merges.
--
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]
