feat!: single endpoint architecture (ADR-026) - Issue #887

BREAKING CHANGE: Renamed agentUrl to endpoint, removed orchestratorUrl and portalUrl

- All routes now go through a single Agent endpoint
- Dynamic policy path changed from /api/v1/policies/dynamic to /api/v1/dynamic-policies
- Added @deprecated annotation on agentUrl() for backwards compatibility
- Updated all tests
- Migration guide added to CHANGELOG

Author: saurabhjain1592

CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to the AxonFlow Java SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-01-05
+
+### Breaking Changes
+
+- **BREAKING**: Renamed `agentUrl` to `endpoint` in `AxonFlowConfig.Builder`
+- **BREAKING**: Removed `orchestratorUrl` and `portalUrl` config options (Agent now proxies all routes per ADR-026)
+- **BREAKING**: Dynamic policy API path changed from `/api/v1/policies/dynamic` to `/api/v1/dynamic-policies`
+
+### Changed
+
+- All SDK methods now route through single Agent endpoint
+- Simplified configuration - only `endpoint()` builder method needed
+- Removed `getOrchestratorUrl()` and `getPortalUrl()` config methods (now return endpoint directly)
+- Added `@Deprecated` annotation on `agentUrl()` builder method for backwards compatibility
+
+### Migration Guide
+
+**Before (v1.x):**
+```java
+AxonFlowConfig config = AxonFlowConfig.builder()
+    .agentUrl("http://localhost:8080")
+    .orchestratorUrl("http://localhost:8081")
+    .portalUrl("http://localhost:8082")
+    .clientId("my-client")
+    .clientSecret("my-secret")
+    .build();
+```
+
+**After (v2.x):**
+```java
+AxonFlowConfig config = AxonFlowConfig.builder()
+    .endpoint("http://localhost:8080")
+    .clientId("my-client")
+    .clientSecret("my-secret")
+    .build();
+```
+
+---
+
 ## [1.13.0] - 2026-01-05
 
 ### Added

src/main/java/com/getaxonflow/sdk/AxonFlow.java

@@ -127,7 +127,7 @@ private AxonFlow(AxonFlowConfig config) {
         this.cache = new ResponseCache(config.getCacheConfig());
         this.asyncExecutor = ForkJoinPool.commonPool();
 
-        logger.info("AxonFlow client initialized for {}", config.getAgentUrl());
+        logger.info("AxonFlow client initialized for {}", config.getEndpoint());
     }
 
     private static ObjectMapper createObjectMapper() {
@@ -1387,9 +1387,9 @@ public void clearCache() {
     // ========================================================================
 
     private Request buildRequest(String method, String path, Object body) {
-        HttpUrl url = HttpUrl.parse(config.getAgentUrl() + path);
+        HttpUrl url = HttpUrl.parse(config.getEndpoint() + path);
         if (url == null) {
-            throw new ConfigurationException("Invalid URL: " + config.getAgentUrl() + path);
+            throw new ConfigurationException("Invalid URL: " + config.getEndpoint() + path);
         }
 
         Request.Builder builder = new Request.Builder()
@@ -1442,9 +1442,9 @@ private Request buildRequest(String method, String path, Object body) {
     }
 
     private Request buildPatchRequest(String path, Object body) {
-        HttpUrl url = HttpUrl.parse(config.getAgentUrl() + path);
+        HttpUrl url = HttpUrl.parse(config.getEndpoint() + path);
         if (url == null) {
-            throw new ConfigurationException("Invalid URL: " + config.getAgentUrl() + path);
+            throw new ConfigurationException("Invalid URL: " + config.getEndpoint() + path);
         }
 
         Request.Builder builder = new Request.Builder()
@@ -2159,21 +2159,11 @@ public String exportCodeGovernanceDataCSV(ExportOptions options) throws IOExcept
     // ========================================================================
 
     /**
-     * Gets the orchestrator URL for Execution Replay API.
-     * Falls back to agent URL with port 8081 if not configured.
+     * Gets the endpoint URL for API requests.
+     * All routes now go through a single endpoint (ADR-026 Single Entry Point).
      */
     private String getOrchestratorUrl() {
-        String orchestratorUrl = config.getOrchestratorUrl();
-        if (orchestratorUrl != null && !orchestratorUrl.isEmpty()) {
-            return orchestratorUrl;
-        }
-        // Default: assume orchestrator is on same host as agent, port 8081
-        try {
-            URI uri = URI.create(config.getAgentUrl());
-            return uri.getScheme() + "://" + uri.getHost() + ":8081";
-        } catch (Exception e) {
-            return "http://localhost:8081";
-        }
+        return config.getEndpoint();
     }
 
     /**
@@ -2226,21 +2216,11 @@ private Request buildOrchestratorRequest(String method, String path, Object body
     }
 
     /**
-     * Gets the portal URL for enterprise PR workflow features.
-     * Falls back to agent URL with port 8082 if not configured.
+     * Gets the endpoint URL for portal API requests.
+     * All routes now go through a single endpoint (ADR-026 Single Entry Point).
      */
     private String getPortalUrl() {
-        String portalUrl = config.getPortalUrl();
-        if (portalUrl != null && !portalUrl.isEmpty()) {
-            return portalUrl;
-        }
-        // Default: assume portal is on same host as agent, port 8082
-        try {
-            URI uri = URI.create(config.getAgentUrl());
-            return uri.getScheme() + "://" + uri.getHost() + ":8082";
-        } catch (Exception e) {
-            return "http://localhost:8082";
-        }
+        return config.getEndpoint();
     }
 
     /**

src/main/java/com/getaxonflow/sdk/AxonFlowConfig.java

@@ -29,7 +29,7 @@
  * <p>Use the builder to create a configuration:
  * <pre>{@code
  * AxonFlowConfig config = AxonFlowConfig.builder()
- *     .agentUrl("http://localhost:8080")
+ *     .endpoint("http://localhost:8080")
  *     .clientId("my-client")
  *     .clientSecret("my-secret")
  *     .build();
@@ -45,12 +45,10 @@ public final class AxonFlowConfig {
     /** Default timeout for HTTP requests. */
     public static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(60);
 
-    /** Default Agent URL. */
-    public static final String DEFAULT_AGENT_URL = "http://localhost:8080";
+    /** Default endpoint URL. */
+    public static final String DEFAULT_ENDPOINT = "http://localhost:8080";
 
-    private final String agentUrl;
-    private final String orchestratorUrl;
-    private final String portalUrl;
+    private final String endpoint;
     private final String clientId;
     private final String clientSecret;
     private final String licenseKey;
@@ -63,9 +61,7 @@ public final class AxonFlowConfig {
     private final String userAgent;
 
     private AxonFlowConfig(Builder builder) {
-        this.agentUrl = normalizeUrl(builder.agentUrl != null ? builder.agentUrl : DEFAULT_AGENT_URL);
-        this.orchestratorUrl = normalizeUrl(builder.orchestratorUrl);
-        this.portalUrl = normalizeUrl(builder.portalUrl);
+        this.endpoint = normalizeUrl(builder.endpoint != null ? builder.endpoint : DEFAULT_ENDPOINT);
         this.clientId = builder.clientId;
         this.clientSecret = builder.clientSecret;
         this.licenseKey = builder.licenseKey;
@@ -81,8 +77,8 @@ private AxonFlowConfig(Builder builder) {
     }
 
     private void validate() {
-        if (agentUrl == null || agentUrl.isEmpty()) {
-            throw new ConfigurationException("agentUrl is required", "agentUrl");
+        if (endpoint == null || endpoint.isEmpty()) {
+            throw new ConfigurationException("endpoint is required", "endpoint");
         }
         // Credentials are optional for community/self-hosted deployments
         // Enterprise features require credentials (validated at method call time)
@@ -106,15 +102,15 @@ private String normalizeUrl(String url) {
     }
 
     /**
-     * Checks if the configured agent URL is localhost.
+     * Checks if the configured endpoint is localhost.
      *
      * @return true if connecting to localhost
      */
     public boolean isLocalhost() {
-        return agentUrl != null && (
-            agentUrl.contains("localhost") ||
-            agentUrl.contains("127.0.0.1") ||
-            agentUrl.contains("[::1]")
+        return endpoint != null && (
+            endpoint.contains("localhost") ||
+            endpoint.contains("127.0.0.1") ||
+            endpoint.contains("[::1]")
         );
     }
 
@@ -123,7 +119,7 @@ public boolean isLocalhost() {
      *
      * <p>Supported environment variables:
      * <ul>
-     *   <li>AXONFLOW_AGENT_URL - The Agent URL</li>
+     *   <li>AXONFLOW_AGENT_URL - The endpoint URL (kept for backwards compatibility)</li>
      *   <li>AXONFLOW_CLIENT_ID - The client ID</li>
      *   <li>AXONFLOW_CLIENT_SECRET - The client secret</li>
      *   <li>AXONFLOW_LICENSE_KEY - The license key</li>
@@ -137,9 +133,10 @@ public boolean isLocalhost() {
     public static AxonFlowConfig fromEnvironment() {
         Builder builder = builder();
 
-        String agentUrl = System.getenv("AXONFLOW_AGENT_URL");
-        if (agentUrl != null && !agentUrl.isEmpty()) {
-            builder.agentUrl(agentUrl);
+        // Keep AXONFLOW_AGENT_URL for backwards compatibility, map to endpoint
+        String endpoint = System.getenv("AXONFLOW_AGENT_URL");
+        if (endpoint != null && !endpoint.isEmpty()) {
+            builder.endpoint(endpoint);
         }
 
         String clientId = System.getenv("AXONFLOW_CLIENT_ID");
@@ -179,16 +176,8 @@ public static AxonFlowConfig fromEnvironment() {
         return builder.build();
     }
 
-    public String getAgentUrl() {
-        return agentUrl;
-    }
-
-    public String getOrchestratorUrl() {
-        return orchestratorUrl;
-    }
-
-    public String getPortalUrl() {
-        return portalUrl;
+    public String getEndpoint() {
+        return endpoint;
     }
 
     public String getClientId() {
@@ -242,21 +231,21 @@ public boolean equals(Object o) {
         AxonFlowConfig that = (AxonFlowConfig) o;
         return debug == that.debug &&
                insecureSkipVerify == that.insecureSkipVerify &&
-               Objects.equals(agentUrl, that.agentUrl) &&
+               Objects.equals(endpoint, that.endpoint) &&
                Objects.equals(clientId, that.clientId) &&
                Objects.equals(licenseKey, that.licenseKey) &&
                mode == that.mode;
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(agentUrl, clientId, licenseKey, mode, debug, insecureSkipVerify);
+        return Objects.hash(endpoint, clientId, licenseKey, mode, debug, insecureSkipVerify);
     }
 
     @Override
     public String toString() {
         return "AxonFlowConfig{" +
-               "agentUrl='" + agentUrl + '\'' +
+               "endpoint='" + endpoint + '\'' +
                ", clientId='" + clientId + '\'' +
                ", mode=" + mode +
                ", timeout=" + timeout +
@@ -268,9 +257,7 @@ public String toString() {
      * Builder for AxonFlowConfig.
      */
     public static final class Builder {
-        private String agentUrl;
-        private String orchestratorUrl;
-        private String portalUrl;
+        private String endpoint;
         private String clientId;
         private String clientSecret;
         private String licenseKey;
@@ -285,41 +272,32 @@ public static final class Builder {
         private Builder() {}
 
         /**
-         * Sets the AxonFlow Agent URL.
+         * Sets the AxonFlow endpoint URL.
+         * All routes now go through a single endpoint (ADR-026 Single Entry Point).
          *
-         * @param agentUrl the Agent URL
+         * @param endpoint the endpoint URL
          * @return this builder
          */
-        public Builder agentUrl(String agentUrl) {
-            this.agentUrl = agentUrl;
+        public Builder endpoint(String endpoint) {
+            this.endpoint = endpoint;
             return this;
         }
 
         /**
-         * Sets the Orchestrator URL for Execution Replay API.
-         *
-         * <p>If not set, defaults to the Agent URL with port 8081.
+         * Sets the AxonFlow Agent URL.
+         * @deprecated Use {@link #endpoint(String)} instead. This method is kept for backwards compatibility.
          *
-         * @param orchestratorUrl the Orchestrator URL
+         * @param agentUrl the Agent URL
          * @return this builder
          */
-        public Builder orchestratorUrl(String orchestratorUrl) {
-            this.orchestratorUrl = orchestratorUrl;
+        @Deprecated
+        public Builder agentUrl(String agentUrl) {
+            this.endpoint = agentUrl;
             return this;
         }
 
-        /**
-         * Sets the Customer Portal URL for enterprise PR workflow features.
-         *
-         * <p>If not set, defaults to the Agent URL with port 8082.
-         *
-         * @param portalUrl the Customer Portal URL
-         * @return this builder
-         */
-        public Builder portalUrl(String portalUrl) {
-            this.portalUrl = portalUrl;
-            return this;
-        }
+        // Note: portalUrl() and orchestratorUrl() methods were removed in v2.0.0
+        // All routes now go through a single endpoint (ADR-026 Single Entry Point)
 
         /**
          * Sets the client ID for authentication.

src/test/java/com/getaxonflow/sdk/AuditReadTest.java

@@ -85,8 +85,8 @@ class AuditReadTest {
     @BeforeEach
     void setUp(WireMockRuntimeInfo wmRuntimeInfo) {
         axonflow = AxonFlow.create(AxonFlowConfig.builder()
-            .agentUrl(wmRuntimeInfo.getHttpBaseUrl())
-            .orchestratorUrl(wmRuntimeInfo.getHttpBaseUrl())
+            .endpoint(wmRuntimeInfo.getHttpBaseUrl())
+            .endpoint(wmRuntimeInfo.getHttpBaseUrl())
             .build());
     }