From 2af9bd3b26686efdb38635bd90d254e07af5c8e3 Mon Sep 17 00:00:00 2001
From: Roman Volosatovs <roman.volosatovs@docker.com>
Date: Mon, 28 Jun 2021 17:30:53 +0200
Subject: [PATCH] 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 | 11 +++++++++--
 api/swagger.yaml                        |  5 +++++
 docs/api/version-history.md             |  3 +++
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/api/server/router/image/image_routes.go b/api/server/router/image/image_routes.go
index a2f2a682f8..9a4648bb49 100644
--- a/api/server/router/image/image_routes.go
+++ b/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
diff --git a/api/swagger.yaml b/api/swagger.yaml
index 0921cc1e2c..b4dbbc1f68 100644
--- a/api/swagger.yaml
+++ b/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."
diff --git a/docs/api/version-history.md b/docs/api/version-history.md
index 8fc14a0b8e..15a759a235 100644
--- a/docs/api/version-history.md
+++ b/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