Add @internalapi annotation to clarify public API surface. (#573)

## What changes are proposed in this pull request?

This PR introduces a new `@InternalApi` annotation and applies it to
internal SDK classes to clearly delineate the public API surface. The
annotation marks classes intended for internal use only, which may
change without notice.

As the SDK grows, it's important to establish a clear contract with
users about what constitutes the stable public API versus internal
implementation details. Without this distinction, users might
inadvertently depend on internal classes, leading to breakage when we
refactor or improve the SDK internals.

The stable public API now consists only of unmarked classes (e.g.,
`DatabricksConfig`, exceptions, error types, extension interfaces like
`CredentialsProvider`). All core implementation classes in
`com.databricks.sdk.core` packages are marked as internal and subject to
change.

## How is this tested?

This is a documentation-only change that adds annotations to existing
classes without modifying their behavior.

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

@@ -3,11 +3,22 @@
 /**
  * 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();
@@ -17,6 +28,10 @@ public interface CredentialsProvider {
    *
    * <p>Note: A new HeaderFactory instance is returned on each invocation.
    *
+   * <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.
+   *
    * @param config the Databricks configuration to use for authentication
    * @return a new HeaderFactory configured for authenticating API requests
    */