Add @InternalApi annotation to clarify public API surface.

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
    */

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

@@ -3,10 +3,12 @@
 import com.databricks.sdk.core.oauth.CachedTokenSource;
 import com.databricks.sdk.core.oauth.OAuthHeaderFactory;
 import com.databricks.sdk.core.utils.OSUtils;
+import com.databricks.sdk.support.InternalApi;
 import java.util.*;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InternalApi
 public class DatabricksCliCredentialsProvider implements CredentialsProvider {
 
   private static final Logger LOG = LoggerFactory.getLogger(DatabricksCliCredentialsProvider.class);

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

@@ -1,9 +1,11 @@
 package com.databricks.sdk.core;
 
 import com.databricks.sdk.core.utils.Cloud;
+import com.databricks.sdk.support.InternalApi;
 import java.util.Arrays;
 import java.util.List;
 
+@InternalApi
 public class DatabricksEnvironment {
   private Cloud cloud;
   private String dnsZone;

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

@@ -1,6 +1,7 @@
 package com.databricks.sdk.core;
 
 import com.databricks.sdk.core.oauth.*;
+import com.databricks.sdk.support.InternalApi;
 import com.google.common.base.Strings;
 import java.util.ArrayList;
 import java.util.List;
@@ -13,6 +14,7 @@
  * Personal Access Tokens (PAT), OAuth, Azure, Google, and OpenID Connect (OIDC). The provider
  * attempts each authentication method in sequence until a valid credential is obtained.
  */
+@InternalApi
 public class DefaultCredentialsProvider implements CredentialsProvider {
   private static final Logger LOG = LoggerFactory.getLogger(DefaultCredentialsProvider.class);
 

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

@@ -3,6 +3,7 @@
 import static com.databricks.sdk.core.utils.GoogleUtils.GCP_SCOPES;
 import static com.databricks.sdk.core.utils.GoogleUtils.SA_ACCESS_TOKEN_HEADER;
 
+import com.databricks.sdk.support.InternalApi;
 import com.google.auth.oauth2.*;
 import com.google.auth.oauth2.IdTokenProvider.Option;
 import java.io.ByteArrayInputStream;
@@ -14,6 +15,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InternalApi
 public class GoogleCredentialsCredentialsProvider implements CredentialsProvider {
 
   private static final Logger LOG =

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

@@ -3,6 +3,7 @@
 import static com.databricks.sdk.core.utils.GoogleUtils.GCP_SCOPES;
 import static com.databricks.sdk.core.utils.GoogleUtils.SA_ACCESS_TOKEN_HEADER;
 
+import com.databricks.sdk.support.InternalApi;
 import com.google.auth.oauth2.GoogleCredentials;
 import com.google.auth.oauth2.IdTokenCredentials;
 import com.google.auth.oauth2.IdTokenProvider;
@@ -12,6 +13,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InternalApi
 public class GoogleIdCredentialsProvider implements CredentialsProvider {
 
   private static final Logger LOG = LoggerFactory.getLogger(GoogleIdCredentialsProvider.class);

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

@@ -1,5 +1,6 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
 import com.databricks.sdk.support.QueryParam;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.google.protobuf.FieldMask;
@@ -17,6 +18,7 @@
  * href="https://cloud.google.com/endpoints/docs/grpc-service-config/reference/rpc/google.api#google.api.HttpRule">the
  * documentation for gRPC transcoding</a> for more details.
  */
+@InternalApi
 public class GrpcTranscodingQueryParamsSerializer {
   public static class QueryParamPair {
     private final String key;

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

@@ -1,5 +1,6 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
 import java.lang.reflect.Field;
 import java.lang.reflect.InvocationTargetException;
 import java.util.*;
@@ -14,6 +15,7 @@
  * the token. This token should be available wherever the DBUtils API is accessible (i.e. in the
  * Spark driver).
  */
+@InternalApi
 public class NotebookNativeCredentialsProvider implements CredentialsProvider {
   private static final Logger LOG =
       LoggerFactory.getLogger(NotebookNativeCredentialsProvider.class);

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

@@ -1,8 +1,10 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
 import java.util.HashMap;
 import java.util.Map;
 
+@InternalApi
 public class PatCredentialsProvider implements CredentialsProvider {
   public static final String PAT = "pat";
 

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

@@ -1,5 +1,8 @@
 package com.databricks.sdk.core;
 
+import com.databricks.sdk.support.InternalApi;
+
+@InternalApi
 public class ProxyConfig {
   private String host;
   private Integer port;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/commons/CommonsHttpClient.java

@@ -10,6 +10,7 @@
 import com.databricks.sdk.core.http.Response;
 import com.databricks.sdk.core.utils.CustomCloseInputStream;
 import com.databricks.sdk.core.utils.ProxyUtils;
+import com.databricks.sdk.support.InternalApi;
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.MalformedURLException;
@@ -37,6 +38,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InternalApi
 public class CommonsHttpClient implements HttpClient {
   /**
    * Builder for CommonsHttpClient. This class is used to construct instances of CommonsHttpClient

databricks-sdk-java/src/main/java/com/databricks/sdk/core/error/AbstractErrorMapper.java

@@ -3,11 +3,13 @@
 import com.databricks.sdk.core.DatabricksError;
 import com.databricks.sdk.core.error.details.ErrorDetails;
 import com.databricks.sdk.core.http.Response;
+import com.databricks.sdk.support.InternalApi;
 import java.util.HashMap;
 import java.util.Map;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InternalApi
 abstract class AbstractErrorMapper {
   private static final Logger LOG = LoggerFactory.getLogger(AbstractErrorMapper.class);
 

databricks-sdk-java/src/main/java/com/databricks/sdk/core/error/ApiErrorBody.java

@@ -1,6 +1,7 @@
 package com.databricks.sdk.core.error;
 
 import com.databricks.sdk.core.error.details.ErrorDetails;
+import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
@@ -10,6 +11,7 @@
  * <p>Unknown properties in the response should be ignored.
  */
 @JsonIgnoreProperties(ignoreUnknown = true)
+@InternalApi
 public class ApiErrorBody {
   private String errorCode;
   private String message;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/error/ApiErrors.java

@@ -4,6 +4,7 @@
 import com.databricks.sdk.core.DatabricksException;
 import com.databricks.sdk.core.error.details.ErrorDetails;
 import com.databricks.sdk.core.http.Response;
+import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.google.api.client.util.Strings;
 import java.io.IOException;
@@ -15,6 +16,7 @@
 import org.apache.commons.io.IOUtils;
 
 /** Helper methods for inspecting the response and errors thrown during API requests. */
+@InternalApi
 public class ApiErrors {
   private static final ObjectMapper MAPPER = new ObjectMapper();
   private static final Pattern HTML_ERROR_REGEX = Pattern.compile("<pre>(.*)</pre>");

databricks-sdk-java/src/main/java/com/databricks/sdk/core/error/ErrorOverride.java

@@ -4,9 +4,11 @@
 import com.databricks.sdk.core.DatabricksException;
 import com.databricks.sdk.core.error.details.ErrorDetails;
 import com.databricks.sdk.core.http.Response;
+import com.databricks.sdk.support.InternalApi;
 import java.lang.reflect.Constructor;
 import java.util.regex.Pattern;
 
+@InternalApi
 public class ErrorOverride<T extends DatabricksError> {
   private final String debugName;
   private final Pattern pathRegex;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/error/PrivateLinkInfo.java

@@ -4,9 +4,11 @@
 import com.databricks.sdk.core.error.details.ErrorDetails;
 import com.databricks.sdk.core.http.Response;
 import com.databricks.sdk.core.utils.Cloud;
+import com.databricks.sdk.support.InternalApi;
 import java.util.HashMap;
 import java.util.Map;
 
+@InternalApi
 public class PrivateLinkInfo {
   private final String serviceName;
   private final String endpointName;

databricks-sdk-java/src/main/java/com/databricks/sdk/core/error/details/ErrorDetailsDeserializer.java

@@ -1,5 +1,6 @@
 package com.databricks.sdk.core.error.details;
 
+import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.core.JsonParser;
 import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.JsonDeserializer;
@@ -15,6 +16,7 @@
  * Custom deserializer for ErrorDetails that converts an array of JSON objects into an ErrorDetails
  * object.
  */
+@InternalApi
 public class ErrorDetailsDeserializer extends JsonDeserializer<ErrorDetails> {
 
   private static final String ERROR_INFO_TYPE = "type.googleapis.com/google.rpc.ErrorInfo";