Add TimeZone header support to REST API (#17344)

[Lexert19]

Description

This PR adds support for the TimeZone header in REST API. The header is parsed in AuthorizationFilter and the time zone is set in the session. Integration tests are added to verify correct handling of valid and invalid time zones.

Closes #17344

---

This PR has:

• been self-reviewed.
  • concurrent read
  • concurrent write
  • concurrent read and write
• added documentation for new or modified features or behaviors.
• added Javadocs for most classes and all non-trivial methods.
• added or updated version, license, or notice information
• added comments explaining the "why" and the intent of the code wherever would not be obvious
  for an unfamiliar reader.
• added unit tests or modified existing tests to cover new code paths, ensuring the threshold
  for code coverage.
• added integration tests.
• been tested in a test IoTDB cluster.

---

Key changed/added classes (or packages if there are too many classes) in this PR

[HTHou]

Add support in
https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/table/v1/impl/RestApiServiceImpl.java and https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/RestApiServiceImpl.java ?

[HTHou]

Another question, why did you pick X-TimeZone? I found there is a document uses Time-Zone.
https://docs.github.com/en/rest/using-the-rest-api/timezones-and-the-rest-api?apiVersion=2026-03-10#using-the-time-zone-header

[HTHou]

And consider add some example in https://github.com/apache/iotdb/tree/master/example/rest-java-example/src/main/java/org/apache/iotdb?

[Lexert19]

Hi @HTHou, thank you for the review! I've updated the PR:

• Renamed the header to Time-Zone
• Added support for V1 and Table V1 API
• Added examples
• Added integration tests for V1 and V2, following the existing code style

[HTHou]

Hi @Lexert19, could you please share this new feature in the dev mail list?

[Copilot]

Pull request overview

This PR introduces request-level time zone handling for the REST APIs by parsing a time zone HTTP header in the REST authorization filter, storing it on the session, and then using the session ZoneId when parsing SQL statements so time literals (and time-based semantics like GROUP BY window alignment) respect the client-provided time zone.

Changes:

• Parse a time zone header in AuthorizationFilter and set the resolved ZoneId into the SessionManager session (reject invalid values with HTTP 400).
• Use the current session ZoneId (instead of ZoneId.systemDefault()) when generating statements in REST v1/v2 and Grafana REST implementations (and table REST statement creation).
• Add integration tests and update Java REST examples to demonstrate header usage.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
integration-test/src/test/java/org/apache/iotdb/db/it/IoTDBRestServiceIT.java	Adds IT coverage for valid/invalid time zone headers on REST v1/v2 query and nonQuery flows.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java	Uses session ZoneId when parsing SQL for v2 query/nonQuery endpoints.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/GrafanaApiServiceImpl.java	Uses session ZoneId when parsing Grafana SQL endpoints in v2.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/RestApiServiceImpl.java	Uses session ZoneId when parsing SQL for v1 query/nonQuery endpoints.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/GrafanaApiServiceImpl.java	Uses session ZoneId when parsing Grafana SQL endpoints in v1.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/table/v1/impl/RestApiServiceImpl.java	Uses the client session’s ZoneId when parsing table-model SQL statements.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/filter/AuthorizationFilter.java	Parses Time-Zone header into ZoneId, aborts request on invalid values, and supplies it to the session.
example/rest-java-example/src/main/java/org/apache/iotdb/TableHttpsExample.java	Adds a table REST query example that includes a time zone header.
example/rest-java-example/src/main/java/org/apache/iotdb/TableHttpExample.java	Adds a table REST query example that includes a time zone header and uses slf4j logging.
example/rest-java-example/src/main/java/org/apache/iotdb/HttpsExample.java	Adds a REST query example that includes a time zone header.
example/rest-java-example/src/main/java/org/apache/iotdb/HttpExample.java	Adds a REST “queryWithTimeZone” example (but currently missing the actual header).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Lexert19]

Hi @HTHou, i have updated the PR to address all the feedback:
-Integration Tests: Adjusted test timestamps to ensure they fall within the GROUP BY time window.
-AuthorizationFilter: Added .trim() to the Time-Zone header to avoid errors with extra spaces.
-Example: Added the missing Time-Zone header to HttpExample.java.