Merge pull request #43235 from thaJeztah/api_wait_fixes

Assorted (documentation) fixes for `POST /containers/{id}/wait`

api/server/router/container/container_routes.go

@@ -336,12 +336,16 @@ func (s *containerRouter) postContainersWait(ctx context.Context, w http.Respons
 		if err := httputils.ParseForm(r); err != nil {
 			return err
 		}
-		switch container.WaitCondition(r.Form.Get("condition")) {
-		case container.WaitConditionNextExit:
-			waitCondition = containerpkg.WaitConditionNextExit
-		case container.WaitConditionRemoved:
-			waitCondition = containerpkg.WaitConditionRemoved
-			legacyRemovalWaitPre134 = versions.LessThan(version, "1.34")
+		if v := r.Form.Get("condition"); v != "" {
+			switch container.WaitCondition(v) {
+			case container.WaitConditionNextExit:
+				waitCondition = containerpkg.WaitConditionNextExit
+			case container.WaitConditionRemoved:
+				waitCondition = containerpkg.WaitConditionRemoved
+				legacyRemovalWaitPre134 = versions.LessThan(version, "1.34")
+			default:
+				return errdefs.InvalidParameter(errors.Errorf("invalid condition: %q", v))
+			}
 		}
 	}
 

api/swagger.yaml

@@ -7018,6 +7018,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -7038,9 +7042,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

client/container_wait.go

@@ -33,7 +33,9 @@ func (cli *Client) ContainerWait(ctx context.Context, containerID string, condit
 	errC := make(chan error, 1)
 
 	query := url.Values{}
-	query.Set("condition", string(condition))
+	if condition != "" {
+		query.Set("condition", string(condition))
+	}
 
 	resp, err := cli.post(ctx, "/containers/"+containerID+"/wait", query, nil, nil)
 	if err != nil {

docs/api/v1.30.yaml

@@ -4389,6 +4389,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -4408,8 +4412,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.31.yaml

@@ -4459,6 +4459,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -4478,8 +4482,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.32.yaml

@@ -5696,6 +5696,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -5715,8 +5719,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.33.yaml

@@ -5701,6 +5701,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -5720,8 +5724,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.34.yaml

@@ -5737,6 +5737,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -5756,8 +5760,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.35.yaml

@@ -5724,6 +5724,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -5743,8 +5747,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.36.yaml

@@ -5748,6 +5748,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -5767,8 +5771,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.37.yaml

@@ -5775,6 +5775,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -5794,8 +5798,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.38.yaml

@@ -5836,6 +5836,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -5855,8 +5859,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.39.yaml

@@ -6552,6 +6552,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -6572,9 +6576,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.40.yaml

@@ -6850,6 +6850,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -6870,9 +6874,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/v1.41.yaml

@@ -7018,6 +7018,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
@@ -7038,9 +7042,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

docs/api/version-history.md

@@ -40,6 +40,8 @@ keywords: "API, Docker, rcli, REST, documentation"
   was used and the architecture was ignored. If no `platform` option is set, the
   host's operating system and architecture as used as default. This change is not
   versioned, and affects all API versions if the daemon has this patch.
+* The `POST /containers/{id}/wait` endpoint now returns a `400` status code if an
+  invalid `condition` is provided (on API 1.30 and up).
 
 ## v1.41 API changes