Separate approaches

Author: VladislavAtanasov95

docs-java/features/connectivity/008-transparent-proxy.mdx

@@ -53,11 +53,14 @@ It uses this destination to forward the request to the target system or to the C
 Consequently, your app does not interact with SAP Destination service or Connectivity service.
 This means your application do not require bindings to these two services, everything is handled by the Transparent Proxy.
 
-## Creating Transparent Proxy Destinations
+## Approach 1: TransparentProxyDestination Builder
 
-The `TransparentProxyDestination` class provides two types of builders for different use cases:
+The `TransparentProxyDestination` class provides explicit destination builders for direct control over transparent proxy connections.
+This approach gives you fine-grained control over individual destination configurations and is recommended for most use cases.
 
-### 1. Destination
+### Creating Destinations
+
+#### Concrete SAP Destination
 
 Allows you to connect to a concrete SAP destination.
 Setting generic headers is allowed but dynamic properties like destination name or fragments is not.
@@ -76,7 +79,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
 `<destination-custom-resource-namespace>` can be omitted if the destination custom resource is created in the same namespace as the application workload.
 :::
 
-### 2. Gateway
+#### Dynamic Destination Gateway
 
 Allows you to connect to arbitrary SAP destinations you have access to.
 As a prerequisite, you have to create a Gateway Destination Custom Resource inside the Kubernetes cluster.
@@ -89,25 +92,26 @@ TransparentProxyDestination destination = TransparentProxyDestination
     .build();
 ```
 
-## Tenant Configuration
+### Configuration Options
+
+#### Tenant Configuration
 
 The SAP Cloud SDK automatically sets the current tenant as tenant ID on a **per-request** basis.
 
 In case a fixed tenant should be used, you can manually set it as follows:
 
-### Destination
+**For Concrete Destinations:**
 
+```java
 // Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified)
 // alternatively, .tenantSubdomain("..") can be used, but only one of the two options may be set
-
-```java
 TransparentProxyDestination destination = TransparentProxyDestination
     .destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
     .tenantId("my-tenant-id")
     .build();
 ```
 
-### Gateway
+**For Gateway Destinations:**
 
 ```java
 // Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified)
@@ -118,13 +122,13 @@ TransparentProxyDestination destination = TransparentProxyDestination
     .build();
 ```
 
-## Authorization Header Configuration
+#### Authorization Header Configuration
 
 The SAP Cloud SDK automatically sets the current user's authorization token in the `Authorization` header on a **per-request** basis.
 
 In case a fixed authorization token should be used, you can manually set it as follows:
 
-### Destination
+**For Concrete Destinations:**
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -133,7 +137,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
     .build();
 ```
 
-### Gateway
+**For Gateway Destinations:**
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -144,18 +148,18 @@ TransparentProxyDestination destination = TransparentProxyDestination
 
 **Note**: When you manually set authorization, it will override the SAP Cloud SDK automatic token handling.
 
-## Migration from Traditional Destinations
+### Migration from Traditional Destinations
 
 Migrating from traditional destination configurations:
 
-### Before (Traditional Destination)
+#### Before (Traditional Destination)
 
 ```java
 Destination destination = DestinationAccessor.getDestination("my-destination");
 HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
 ```
 
-### After (Transparent Proxy - Gateway)
+#### After (Transparent Proxy - Gateway)
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -164,7 +168,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
 HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
 ```
 
-### After (Transparent Proxy - Destination)
+#### After (Transparent Proxy - Concrete Destination)
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -173,48 +177,16 @@ TransparentProxyDestination destination = TransparentProxyDestination
 HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
 ```
 
-## Troubleshooting
-
-### Common Issues
-
-1. **Missing destination name for gateway**: Ensure the destination name is provided as the first parameter to `.gateway(<destination-name>, <destination-custom-resource-name>.<destination-custom-resource-namespace>)`
-2. **Tenant context not available**: Verify tenant information is properly set in the request context
-3. **Authentication failures**: Check that authentication headers and parameters are correctly configured
-4. **Network connectivity**: Verify that the Transparent Proxy is accessible from your environment
-
-### Evaluating Transparent Proxy Headers
-
-When using proxy servers it can be difficult to troubleshoot issues as it is often not obvious where exactly the error occurred.
-For example, with the Transparent Proxy errors might occur on the target system (e.g. OData service), the Destination Service or the Transparent Proxy itself.
-
-To make troubleshooting easier the Transparent Proxy adds additional response headers to provide more information about where an error occurred.
-For the above example of executing OData requests you can access the response headers as follows:
-
-```java
-try {
-    // execute OData request
-} catch (ODataResponseException e) {
-    System.out.println(e.getHttpCode());
-    // the Transparent Proxy will attach additional response headers in case an error occurred
-    System.out.println(e.getHttpHeaders());
-}
-```
-
-#### List of headers added by the Transparent Proxy
+## Approach 2: Transparent Proxy Loader
 
-- `X-Error-Origin` - the source of the error
-- `X-Proxy-Server` - the proxy server (Transparent Proxy)
-- `X-Error-Message` - thorough error message
-- `X-Error-Internal-Code` - set only when the source of the error is the XSUAA or Destination service.
-  The value is the HTTP code returned from one of these services.
-- `X-Request-Id` is sent with the response in all requests, both successful and failed
+The `TransparentProxy` class provides a `DestinationLoader` that enables routing **all destination traffic** through a single registered gateway host.
+This approach provides centralized proxy configuration where all destination requests are automatically routed through the configured gateway without requiring explicit destination builders.
 
-For more information, see [Troubleshooting](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/transparent-proxy-troubleshooting)
+### When to Use This Approach
 
-## Transparent Proxy Loader
-
-The `TransparentProxy` class is a `DestinationLoader` that enables routing all destination traffic through a single registered gateway host.
-This provides a centralized approach to proxy configuration where all destination requests are automatically routed through the configured gateway.
+Use the Transparent Proxy Loader when:
+- You want all destinations to automatically route through a single transparent proxy gateway
+- You prefer a centralized configuration approach
 
 ### Registration Methods
 
@@ -253,6 +225,44 @@ TransparentProxy.register("<destination-gateway-host>", 8080);
 Destination destination = DestinationAccessor.getDestination("my-destination");
 ```
 
+## Troubleshooting
+
+### Common Issues
+
+1. **Missing destination name for gateway**: Ensure the destination name is provided as the first parameter to `.gateway(<destination-name>, <destination-custom-resource-name>.<destination-custom-resource-namespace>)`
+2. **Tenant context not available**: Verify tenant information is properly set in the request context
+3. **Authentication failures**: Check that authentication headers and parameters are correctly configured
+4. **Network connectivity**: Verify that the Transparent Proxy is accessible from your environment
+
+### Evaluating Transparent Proxy Headers
+
+When using proxy servers it can be difficult to troubleshoot issues as it is often not obvious where exactly the error occurred.
+For example, with the Transparent Proxy errors might occur on the target system (e.g. OData service), the Destination Service or the Transparent Proxy itself.
+
+To make troubleshooting easier the Transparent Proxy adds additional response headers to provide more information about where an error occurred.
+For the above example of executing OData requests you can access the response headers as follows:
+
+```java
+try {
+    // execute OData request
+} catch (ODataResponseException e) {
+    System.out.println(e.getHttpCode());
+    // the Transparent Proxy will attach additional response headers in case an error occurred
+    System.out.println(e.getHttpHeaders());
+}
+```
+
+#### List of headers added by the Transparent Proxy
+
+- `X-Error-Origin` - the source of the error
+- `X-Proxy-Server` - the proxy server (Transparent Proxy)
+- `X-Error-Message` - thorough error message
+- `X-Error-Internal-Code` - set only when the source of the error is the XSUAA or Destination service.
+  The value is the HTTP code returned from one of these services.
+- `X-Request-Id` is sent with the response in all requests, both successful and failed
+
+For more information, see [Troubleshooting](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/transparent-proxy-troubleshooting)
+
 ## Related Documentation
 
 - [HTTP Client](http-client) - For using destinations with HTTP clients