nastra commented on code in PR #17727:
URL: https://github.com/apache/iceberg/pull/17727#discussion_r4495933524
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -25,9 +25,61 @@ 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 SHOULD
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:
Review Comment:
nit: I feel like the second example should fit into the previous line
--
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]
