client: deprecate CommonAPIClient interface

thaJeztah · thaJeztah · commit 2997c0ddc00b · 2025-02-04T17:21:31.000+01:00
The CommonAPIClient was used to define all the stable interfaces,
and combined with the experimental ones through APIClient. In theory,
this would allow someone to make sure they only depended on non-experimental
methods or to implement an alternative client that only implements the
stable methods.

While there are users currently using this interface, all those uses
depend on the actual client implementation, not a custom one, so they
should be able to switch to use APIClient instead. In the meantime,
start with deprecating, but keeping the interface the same for now,
scheduling it to become an alias, and removed in a future release.

Signed-off-by: Sebastiaan van Stijn &lt;github@gone.nl&gt;
diff --git a/client/checkpoint.go b/client/checkpoint.go
@@ -6,11 +6,11 @@ import (
 	"github.com/docker/docker/api/types/checkpoint"
 )
 
-type apiClientExperimental interface {
-	CheckpointAPIClient
-}
-
-// CheckpointAPIClient defines API client methods for the checkpoints
+// CheckpointAPIClient defines API client methods for the checkpoints.
+//
+// Experimental: checkpoint and restore is still an experimental feature,
+// and only available if the daemon is running with experimental features
+// enabled.
 type CheckpointAPIClient interface {
 	CheckpointCreate(ctx context.Context, container string, options checkpoint.CreateOptions) error
 	CheckpointDelete(ctx context.Context, container string, options checkpoint.DeleteOptions) error
diff --git a/client/client.go b/client/client.go
@@ -99,6 +99,9 @@ const DummyHost = "api.moby.localhost"
 // recent version before negotiation was introduced.
 const fallbackAPIVersion = "1.24"
 
+// Ensure that Client always implements APIClient.
+var _ APIClient = &Client{}
+
 // Client is the API client that performs all operations
 // against a docker server.
 type Client struct {
diff --git a/client/client_interfaces.go b/client/client_interfaces.go
@@ -20,7 +20,17 @@ import (
 )
 
 // CommonAPIClient is the common methods between stable and experimental versions of APIClient.
-type CommonAPIClient interface {
+//
+// Deprecated: use [APIClient] instead. This type will be an alias for [APIClient] in the next release, and removed after.
+type CommonAPIClient = stableAPIClient
+
+// APIClient is an interface that clients that talk with a docker server must implement.
+type APIClient interface {
+	stableAPIClient
+	CheckpointAPIClient // CheckpointAPIClient is still experimental.
+}
+
+type stableAPIClient interface {
 	ConfigAPIClient
 	ContainerAPIClient
 	DistributionAPIClient
diff --git a/client/interface_stable.go b/client/interface_stable.go
