Skip to content

Automatically negotiate API version to use #2547

Open
Open
Automatically negotiate API version to use#2547
@AB-xdev

Description

@AB-xdev
AB-xdev
opened on Nov 24, 2025

The go client has an option to automatically negotiate what API version should be selected.

This could also be used here.

Fork example calling `/version` returns the following: 
{
  "Platform" : {
    "Name" : "Docker Desktop 4.51.0 (210443)"
  },
  "Components" : [ {
    "Name" : "Engine",
    "Version" : "28.5.2",
    "Details" : {
      "ApiVersion" : "1.51",
      "Arch" : "amd64",
      "BuildTime" : "2025-11-05T14:43:25.000000000+00:00",
      "Experimental" : "false",
      "GitCommit" : "89c5e8f",
      "GoVersion" : "go1.25.3",
      "KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
      "MinAPIVersion" : "1.24",
      "Os" : "linux"
    }
  }, {
    "Name" : "containerd",
    "Version" : "v1.7.29",
    "Details" : {
      "GitCommit" : "442cb34bda9a6a0fed82a2ca7cade05c5c749582"
    }
  }, {
    "Name" : "runc",
    "Version" : "1.3.3",
    "Details" : {
      "GitCommit" : "v1.3.3-0-gd842d771"
    }
  }, {
    "Name" : "docker-init",
    "Version" : "0.19.0",
    "Details" : {
      "GitCommit" : "de40ad0"
    }
  } ],
  "Version" : "28.5.2",
  "ApiVersion" : "1.51",
  "MinAPIVersion" : "1.24",
  "GitCommit" : "89c5e8f",
  "GoVersion" : "go1.25.3",
  "Os" : "linux",
  "Arch" : "amd64",
  "KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
  "BuildTime" : "2025-11-05T14:43:25.000000000+00:00"
}

{
  "Platform" : {
    "Name" : "Docker Desktop 4.52.0 (210994)"
  },
  "Components" : [ {
    "Name" : "Engine",
    "Version" : "29.0.1",
    "Details" : {
      "ApiVersion" : "1.52",
      "Arch" : "amd64",
      "BuildTime" : "2025-11-14T16:17:57.000000000+00:00",
      "Experimental" : "false",
      "GitCommit" : "198b5e3",
      "GoVersion" : "go1.25.4",
      "KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
      "MinAPIVersion" : "1.44",
      "Os" : "linux"
    }
  }, {
    "Name" : "containerd",
    "Version" : "v2.1.5",
    "Details" : {
      "GitCommit" : "fcd43222d6b07379a4be9786bda52438f0dd16a1"
    }
  }, {
    "Name" : "runc",
    "Version" : "1.3.3",
    "Details" : {
      "GitCommit" : "v1.3.3-0-gd842d771"
    }
  }, {
    "Name" : "docker-init",
    "Version" : "0.19.0",
    "Details" : {
      "GitCommit" : "de40ad0"
    }
  } ],
  "Version" : "29.0.1",
  "ApiVersion" : "1.52",
  "MinAPIVersion" : "1.44",
  "GitCommit" : "198b5e3",
  "GoVersion" : "go1.25.4",
  "Os" : "linux",
  "Arch" : "amd64",
  "KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
  "BuildTime" : "2025-11-14T16:17:57.000000000+00:00"
}

The MinAPIVersion attribute could be used to compare it with the client's version.
If ClientAPIVersion < MinAPIVersion the client could log an warning and force the use of MinAPIVersion - this should prevent hard errors at the cost that the API might be incompatible and not work 100%.

The same can also be done the other way around if ClientAPIVersion > ApiVersion.

NOTE: It's currently possible to just omit the /<version> prefix from the paths.
However using the API without a version-prefix is deprecated and will be removed in a future release.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions