API: add shared-size parameter to image queries

The reasoning for this change is to be able to query image shared size without having to rely on the more heavyweight `/system/df` endpoint.

Signed-off-by: Roman Volosatovs <roman.volosatovs@docker.com>

api/server/router/image/image_routes.go

@@ -236,9 +236,16 @@ func (s *imageRouter) getImagesJSON(ctx context.Context, w http.ResponseWriter,
 		}
 	}
 
+	var sharedSize bool
+	if versions.GreaterThanOrEqualTo(version, "1.42") {
+		// NOTE: Support for the "shared-size" parameter was added in API 1.42.
+		sharedSize = httputils.BoolValue(r, "shared-size")
+	}
+
 	images, err := s.backend.Images(ctx, types.ImageListOptions{
-		Filters: imageFilters,
-		All:     httputils.BoolValue(r, "all"),
+		All:        httputils.BoolValue(r, "all"),
+		Filters:    imageFilters,
+		SharedSize: sharedSize,
 	})
 	if err != nil {
 		return err

api/swagger.yaml

@@ -7202,6 +7202,11 @@ paths:
             - `reference`=(`<image-name>[:<tag>]`)
             - `since`=(`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`)
           type: "string"
+        - name: "shared-size"
+          in: "query"
+          description: "Compute and show shared size as a `SharedSize` field on each image."
+          type: "boolean"
+          default: false
         - name: "digests"
           in: "query"
           description: "Show digest information as a `RepoDigests` field on each image."

docs/api/version-history.md

@@ -21,6 +21,9 @@ keywords: "API, Docker, rcli, REST, documentation"
   was introduced in API 1.31 as part of an experimental feature, and no longer
   used since API 1.40.
   Use field `BuildCache` instead to track storage used by the builder component.
+* `GET /images/json` now accepts query parameter `shared-size`. When set `true`,
+  images returned will include `SharedSize`, which provides the size on disk shared
+  with other images present on the system.
 
 ## v1.41 API changes