feat(api-core): centralize rest transcoding helpers (#17765)

introduces a generic REST Transcoding helper under
`google.api_core.gapic_v1.rest_transcoding`.

Scope of Changes:
- **`rest_helpers.py`**: A centralized, parameters-driven generic
utility `transcode()` that replaces the redundant code generated inside
the client REST transport constructors (query parameter JSON parsing,
required field default checking, body parsing, and numeric enum
serialization).
- **`__init__.py`**: Registered lazy-loading for the module.
- **`conftest.py`**: Added session-scoped mock fixtures for mTLS
variables to prevent local workstation client certificate leakage during
python unit tests.
- **`test_rest_transcoding.py`**: A comprehensive test suite validating
transcoding behavior for query parameters, nested fields, required field
default injection, and numeric enums.

This is the runtime package companion to the generator PR.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: hebaalazzeh

packages/google-api-core/google/api_core/rest_helpers.py

@@ -15,7 +15,14 @@
 """Helpers for rest transports."""
 
 import functools
+import json
 import operator
+from typing import Any, Dict, List, Optional, Tuple
+
+from google.api_core import path_template
+from google.protobuf import json_format
+
+__all__ = ["flatten_query_params", "transcode", "transcode_request"]
 
 
 def flatten_query_params(obj, strict=False):
@@ -107,3 +114,64 @@ def _canonicalize(obj, strict=False):
             value = value.lower()
         return value
     return obj
+
+
+def transcode_request(
+    http_options: List[Dict[str, str]],
+    request: Any,
+    required_fields_default_values: Optional[Dict[str, Any]] = None,
+    rest_numeric_enums: bool = False,
+) -> Tuple[Dict[str, Any], Optional[str], Dict[str, Any]]:
+    """Transcodes a request into HTTP method, URI, body, and query parameters.
+
+    Args:
+        http_options (List[Dict[str, str]]): List of HTTP transcoding rules.
+        request (Any): The protobuf or proto-plus request message.
+        required_fields_default_values (Optional[Dict[str, Any]]): Dictionary
+            of required fields default values to merge into query parameters if missing.
+        rest_numeric_enums (bool): Whether to encode enums as integers.
+
+    Returns:
+        Tuple[Dict[str, Any], Optional[str], Dict[str, Any]]: A tuple containing:
+            - The raw transcoded request dictionary (containing keys like 'uri', 'method').
+            - The serialized request body JSON string, or None if no body.
+            - The query parameters dictionary.
+    """
+    if request is None:
+        raise TypeError("request cannot be None")
+
+    # Convert proto-plus message to its underlying protobuf message if needed
+    pb_request = getattr(request, "_pb", request)
+
+    transcoded_request = path_template.transcode(http_options, pb_request)
+
+    body_json = None
+    if transcoded_request.get("body") is not None:
+        body_json = json_format.MessageToJson(
+            transcoded_request["body"],
+            use_integers_for_enums=rest_numeric_enums,
+        )
+
+    query_params_json = {}
+    if transcoded_request.get("query_params") is not None:
+        query_params_json = json.loads(
+            json_format.MessageToJson(
+                transcoded_request["query_params"],
+                use_integers_for_enums=rest_numeric_enums,
+            )
+        )
+
+    # If required_fields_default_values is provided, we merge default values for missing
+    # required fields into the query parameters.
+    if required_fields_default_values:
+        for k, v in required_fields_default_values.items():
+            if k not in query_params_json:
+                query_params_json[k] = v
+
+    if rest_numeric_enums:
+        query_params_json["$alt"] = "json;enum-encoding=int"
+
+    return transcoded_request, body_json, query_params_json
+
+
+transcode = transcode_request

packages/google-api-core/tests/conftest.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from unittest import mock
+
+import pytest
+
+
+@pytest.fixture(scope="session", autouse=True)
+def mock_mtls_env():
+    """Autouse session-scoped fixture to isolate unit tests from workstation mTLS environments."""
+    with mock.patch.dict(
+        os.environ,
+        {
+            "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false",
+            "CLOUDSDK_CONTEXT_AWARE_USE_CLIENT_CERTIFICATE": "false",
+        },
+    ):
+        yield

packages/google-api-core/tests/unit/test_rest_helpers.py

@@ -12,9 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import json
+from unittest import mock
+
 import pytest
 
 from google.api_core import rest_helpers
+from google.api_core.rest_helpers import transcode_request
+from google.protobuf import descriptor_pb2
 
 
 def test_flatten_simple_value():
@@ -92,3 +97,182 @@ def test_flatten_repeated_list():
 
     with pytest.raises(ValueError):
         rest_helpers.flatten_query_params(obj)
+
+
+def test_transcode_basic():
+    # We use FieldDescriptorProto as it has standard primitive fields and nested messages.
+    http_options = [
+        {
+            "method": "get",
+            "uri": "/v1/test/{name}",
+        }
+    ]
+
+    request = descriptor_pb2.FieldDescriptorProto()
+    request.name = "my-field"
+    request.number = 123
+
+    transcoded, body, query_params = transcode_request(http_options, request)
+
+    assert transcoded["method"] == "get"
+    assert transcoded["uri"] == "/v1/test/my-field"
+    assert body is None
+    # 'number' should be in query parameters
+    assert "number" in query_params
+    assert query_params["number"] == 123
+
+
+def test_transcode_with_nested_field():
+    http_options = [
+        {
+            "method": "get",
+            "uri": "/v1/test/{options.deprecated}/{name}",
+        }
+    ]
+
+    request = descriptor_pb2.FieldDescriptorProto()
+    request.name = "my-field"
+    request.options.deprecated = True
+    request.number = 123
+
+    transcoded, body, query_params = transcode_request(http_options, request)
+
+    assert transcoded["method"] == "get"
+    assert transcoded["uri"] == "/v1/test/True/my-field"
+    assert body is None
+    assert "number" in query_params
+    assert query_params["number"] == 123
+
+
+def test_transcode_with_body():
+    http_options = [
+        {
+            "method": "post",
+            "uri": "/v1/test/{name}",
+            "body": "options",
+        }
+    ]
+
+    request = descriptor_pb2.FieldDescriptorProto()
+    request.name = "my-field"
+    request.options.deprecated = True
+    request.number = 123
+
+    transcoded, body, query_params = transcode_request(http_options, request)
+
+    assert transcoded["method"] == "post"
+    assert transcoded["uri"] == "/v1/test/my-field"
+    assert body is not None
+    body_data = json.loads(body)
+    assert body_data["deprecated"] is True
+    # Query parameters should not contain 'options' (the body)
+    assert "number" in query_params
+    assert query_params["number"] == 123
+    assert "options" not in query_params
+
+
+def test_transcode_with_required_fields_default_values():
+    http_options = [
+        {
+            "method": "get",
+            "uri": "/v1/test/{name}",
+        }
+    ]
+
+    request = descriptor_pb2.FieldDescriptorProto()
+    request.name = "my-field"
+
+    required_defaults = {"requiredQueryParam": "default-val"}
+
+    transcoded, body, query_params = transcode_request(
+        http_options,
+        request,
+        required_fields_default_values=required_defaults,
+    )
+
+    assert query_params["requiredQueryParam"] == "default-val"
+
+
+def test_transcode_with_numeric_enums():
+    http_options = [
+        {
+            "method": "get",
+            "uri": "/v1/test/{name}",
+        }
+    ]
+
+    request = descriptor_pb2.FieldDescriptorProto()
+    request.name = "my-field"
+    request.type = descriptor_pb2.FieldDescriptorProto.TYPE_STRING
+
+    # Without numeric enums
+    _, _, query_params = transcode_request(
+        http_options, request, rest_numeric_enums=False
+    )
+    assert query_params["type"] == "TYPE_STRING"
+
+    # With numeric enums
+    _, _, query_params = transcode_request(
+        http_options, request, rest_numeric_enums=True
+    )
+    # Type number for TYPE_STRING is 9
+    assert query_params["type"] == 9
+    assert query_params["$alt"] == "json;enum-encoding=int"
+
+
+def test_transcode_no_query_params():
+    http_options = [{"method": "get", "uri": "/v1/test"}]
+    request = descriptor_pb2.FieldDescriptorProto()
+
+    with mock.patch(
+        "google.api_core.path_template.transcode",
+        return_value={"method": "get", "uri": "/v1/test"},
+    ):
+        transcoded, body, query_params = transcode_request(http_options, request)
+        assert query_params == {}
+
+
+def test_transcode_with_required_fields_existing_key():
+    http_options = [
+        {
+            "method": "get",
+            "uri": "/v1/test",
+        }
+    ]
+
+    request = descriptor_pb2.FieldDescriptorProto()
+    request.name = "custom-name"
+
+    required_defaults = {"name": "default-name"}
+
+    transcoded, body, query_params = transcode_request(
+        http_options,
+        request,
+        required_fields_default_values=required_defaults,
+    )
+
+    assert query_params["name"] == "custom-name"
+
+
+def test_transcode_alias():
+    from google.api_core.rest_helpers import transcode as tr_top
+
+    assert tr_top is transcode_request
+
+
+def test_transcode_request_invalid_request():
+    http_options = [{"method": "get", "uri": "/v1/test"}]
+    with pytest.raises(TypeError, match="request cannot be None"):
+        transcode_request(http_options, None)
+
+
+def test_transcode_request_proto_plus_wrapper():
+    http_options = [{"method": "get", "uri": "/v1/test/{name}"}]
+    mock_pb = descriptor_pb2.FieldDescriptorProto()
+    mock_pb.name = "proto-plus-field"
+
+    mock_proto_plus = mock.Mock()
+    mock_proto_plus._pb = mock_pb
+
+    transcoded, _, _ = transcode_request(http_options, mock_proto_plus)
+    assert transcoded["uri"] == "/v1/test/proto-plus-field"