Add internal API annotation

Author: renaudhartert-db

NEXT_CHANGELOG.md

@@ -10,6 +10,11 @@
 
 ### Documentation
 
+* Add `@InternalApi` annotation to clarify the public API surface. Classes 
+  marked with `@InternalApi` are intended for internal use only and may change
+  without notice. Only unmarked classes (e.g., `DatabricksConfig`, exceptions, 
+  error types, extension interfaces) are part of the stable public API.
+
 ### Internal Changes
 
 ### API Changes

databricks-sdk-java/src/main/java/com/databricks/sdk/core/ApiClient.java

@@ -14,6 +14,7 @@
 import com.databricks.sdk.core.utils.SystemTimer;
 import com.databricks.sdk.core.utils.Timer;
 import com.databricks.sdk.support.Header;
+import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.JavaType;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -31,6 +32,7 @@
  * Simplified REST API client with retries, JSON POJO SerDe through Jackson and exception POJO
  * guessing
  */
+@InternalApi
 public class ApiClient {
   public static class Builder {
     private Timer timer;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/AzureCliCredentialsProvider.java

@@ -4,11 +4,13 @@
 import com.databricks.sdk.core.oauth.OAuthHeaderFactory;
 import com.databricks.sdk.core.oauth.Token;
 import com.databricks.sdk.core.utils.AzureUtils;
+import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import java.util.*;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InternalApi
 public class AzureCliCredentialsProvider implements CredentialsProvider {
   private final ObjectMapper mapper = new ObjectMapper();
   private static final Logger LOG = LoggerFactory.getLogger(AzureCliCredentialsProvider.class);

databricks-sdk-java/src/main/java/com/databricks/sdk/core/AzureEnvironment.java

@@ -1,5 +1,6 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -10,6 +11,7 @@
  * resources vary depending on the cloud environment: public, germany, govcloud, or china. Depending
  * on the operation, tokens scoped to a specific endpoint are needed.
  */
+@InternalApi
 public class AzureEnvironment {
   private String name;
   private String serviceManagementEndpoint;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/BasicCredentialsProvider.java

@@ -1,9 +1,11 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
 import java.util.Base64;
 import java.util.HashMap;
 import java.util.Map;
 
+@InternalApi
 public class BasicCredentialsProvider implements CredentialsProvider {
   public static final String BASIC = "basic";
 

databricks-sdk-java/src/main/java/com/databricks/sdk/core/BodyLogger.java

@@ -1,12 +1,14 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.core.TreeNode;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import java.util.*;
 
+@InternalApi
 class BodyLogger {
   private final Set<String> redactKeys =
       new HashSet<String>() {

databricks-sdk-java/src/main/java/com/databricks/sdk/core/CliTokenSource.java

@@ -4,6 +4,7 @@
 import com.databricks.sdk.core.oauth.TokenSource;
 import com.databricks.sdk.core.utils.Environment;
 import com.databricks.sdk.core.utils.OSUtils;
+import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import java.io.IOException;
@@ -18,6 +19,7 @@
 import java.util.List;
 import org.apache.commons.io.IOUtils;
 
+@InternalApi
 public class CliTokenSource implements TokenSource {
   private List<String> cmd;
   private String tokenTypeField;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/ConfigAttributeAccessor.java

@@ -1,10 +1,12 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
 import java.lang.reflect.Field;
 import java.time.Duration;
 import java.util.Map;
 import java.util.Objects;
 
+@InternalApi
 class ConfigAttributeAccessor {
   private final ConfigAttribute configAttribute;
   private final Field field;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/ConfigLoader.java

@@ -1,6 +1,7 @@
 package com.databricks.sdk.core;
 
 import com.databricks.sdk.core.utils.Environment;
+import com.databricks.sdk.support.InternalApi;
 import java.io.FileNotFoundException;
 import java.io.FileReader;
 import java.io.IOException;
@@ -15,6 +16,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InternalApi
 public class ConfigLoader {
   private static final Logger LOG = LoggerFactory.getLogger(ConfigLoader.class);
 

databricks-sdk-java/src/main/java/com/databricks/sdk/core/CredentialsProvider.java

@@ -1,7 +1,39 @@
 package com.databricks.sdk.core;
 
+/**
+ * CredentialsProvider is an interface that provides a HeaderFactory to authenticate requests to the
+ * Databricks API.
+ *
+ * <p>Users can implement this interface to provide custom authentication mechanisms. Once
+ * implemented, the custom provider can be set on {@link DatabricksConfig} using {@link
+ * DatabricksConfig#setCredentialsProvider(CredentialsProvider)}.
+ *
+ * <p><b>Note:</b> The methods in this interface are called internally by the SDK clients
+ * (WorkspaceClient and AccountClient) during request authentication. Users implementing this
+ * interface should not call these methods directly.
+ */
 public interface CredentialsProvider {
+  /**
+   * Returns the authentication type identifier for this credentials provider.
+   *
+   * <p><b>This method is called internally by the SDK</b> and should not be invoked directly by
+   * users. It is used for logging and user-agent identification purposes.
+   *
+   * @return the authentication type as a string
+   */
   String authType();
 
+  /**
+   * Creates and returns a new HeaderFactory to authenticate requests to the Databricks API.
+   *
+   * <p><b>This method is called internally by the SDK</b> during client initialization and should
+   * not be invoked directly by users. The SDK will call this method to obtain a HeaderFactory that
+   * will be used to add authentication headers to each API request.
+   *
+   * <p>Note: A new HeaderFactory instance is returned on each invocation.
+   *
+   * @param config the Databricks configuration to use for authentication
+   * @return a new HeaderFactory configured for authenticating API requests
+   */
   HeaderFactory configure(DatabricksConfig config);
 }