Merge pull request #35129 from thaJeztah/add-content-length-headers

API docs: add information about Content-Length header

docs/api/v1.18.md

@@ -23,6 +23,8 @@ redirect_from:
  - The API tends to be REST, but for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.
+ - A `Content-Length` header should be present in `POST` requests to endpoints
+   that expect a body.
 
 ## 2. Endpoints
 
@@ -131,6 +133,7 @@ Create a container
 
     POST /v1.18/containers/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
            "Hostname": "",
@@ -1077,6 +1080,7 @@ Copy files or folders of container `id`
 
     POST /v1.18/containers/4fa6e0f0c678/copy HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Resource": "test.txt"
@@ -1556,6 +1560,7 @@ Get the default username and email
 
     POST /v1.18/auth HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "username": "hannibal",
@@ -1701,6 +1706,7 @@ Create a new image from a container's changes
 
     POST /v1.18/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Hostname": "",
@@ -1865,6 +1871,7 @@ See the [image tarball format](#image-tarball-format) for more details.
 
     POST /v1.18/images/load
     Content-Type: application/x-tar
+    Content-Length: 12345
 
     Tarball in body
 
@@ -1908,6 +1915,7 @@ Sets up an exec instance in a running container `id`
 
     POST /v1.18/containers/e90e34656806/exec HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "AttachStdin": true,
@@ -1953,6 +1961,7 @@ interactive session with the `exec` command.
 
     POST /v1.18/exec/e90e34656806/start HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
      "Detach": false,

docs/api/v1.19.md

@@ -25,6 +25,8 @@ redirect_from:
    `stdin` and `stderr`.
  - When the client API version is newer than the daemon's, these calls return an HTTP
    `400 Bad Request` error message.
+ - A `Content-Length` header should be present in `POST` requests to endpoints
+   that expect a body.
 
 ## 2. Endpoints
 
@@ -133,6 +135,7 @@ Create a container
 
     POST /v1.19/containers/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
            "Hostname": "",
@@ -1116,6 +1119,7 @@ Copy files or folders of container `id`
 
     POST /v1.19/containers/4fa6e0f0c678/copy HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Resource": "test.txt"
@@ -1628,6 +1632,7 @@ Get the default username and email
 
     POST /v1.19/auth HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "username": "hannibal",
@@ -1777,6 +1782,7 @@ Create a new image from a container's changes
 
     POST /v1.19/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Hostname": "",
@@ -1945,6 +1951,7 @@ See the [image tarball format](#image-tarball-format) for more details.
 
     POST /v1.19/images/load
     Content-Type: application/x-tar
+    Content-Length: 12345
 
     Tarball in body
 
@@ -1988,6 +1995,7 @@ Sets up an exec instance in a running container `id`
 
     POST /v1.19/containers/e90e34656806/exec HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "AttachStdin": true,
@@ -2036,6 +2044,7 @@ interactive session with the `exec` command.
 
     POST /v1.19/exec/e90e34656806/start HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
      "Detach": false,

docs/api/v1.20.md

@@ -23,6 +23,10 @@ redirect_from:
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.
+ - When the client API version is newer than the daemon's, these calls return an HTTP
+   `400 Bad Request` error message.
+ - A `Content-Length` header should be present in `POST` requests to endpoints
+   that expect a body.
 
 ## 2. Endpoints
 
@@ -131,6 +135,7 @@ Create a container
 
     POST /v1.20/containers/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
            "Hostname": "",
@@ -1125,6 +1130,7 @@ Copy files or folders of container `id`
 
     POST /v1.20/containers/4fa6e0f0c678/copy HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Resource": "test.txt"
@@ -1776,6 +1782,7 @@ Get the default username and email
 
     POST /v1.20/auth HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "username": "hannibal",
@@ -1926,6 +1933,7 @@ Create a new image from a container's changes
 
     POST /v1.20/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Hostname": "",
@@ -2100,6 +2108,7 @@ See the [image tarball format](#image-tarball-format) for more details.
 
     POST /v1.20/images/load
     Content-Type: application/x-tar
+    Content-Length: 12345
 
     Tarball in body
 
@@ -2143,6 +2152,7 @@ Sets up an exec instance in a running container `id`
 
     POST /v1.20/containers/e90e34656806/exec HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "AttachStdin": true,
@@ -2191,6 +2201,7 @@ interactive session with the `exec` command.
 
     POST /v1.20/exec/e90e34656806/start HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
      "Detach": false,

docs/api/v1.21.md

@@ -25,6 +25,8 @@ redirect_from:
    `stdin` and `stderr`.
  - When the client API version is newer than the daemon's, these calls return an HTTP
    `400 Bad Request` error message.
+ - A `Content-Length` header should be present in `POST` requests to endpoints
+   that expect a body.
 
 ## 2. Endpoints
 
@@ -137,6 +139,7 @@ Create a container
 
     POST /v1.21/containers/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
            "Hostname": "",
@@ -1208,6 +1211,7 @@ Copy files or folders of container `id`
 
     POST /v1.21/containers/4fa6e0f0c678/copy HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Resource": "test.txt"
@@ -1929,6 +1933,7 @@ Get the default username and email
 
     POST /v1.21/auth HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "username": "hannibal",
@@ -2081,6 +2086,7 @@ Create a new image from a container's changes
 
     POST /v1.21/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Hostname": "",
@@ -2256,6 +2262,7 @@ See the [image tarball format](#image-tarball-format) for more details.
 
     POST /v1.21/images/load
     Content-Type: application/x-tar
+    Content-Length: 12345
 
     Tarball in body
 
@@ -2299,6 +2306,7 @@ Sets up an exec instance in a running container `id`
 
     POST /v1.21/containers/e90e34656806/exec HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "AttachStdin": true,
@@ -2351,6 +2359,7 @@ interactive session with the `exec` command.
 
     POST /v1.21/exec/e90e34656806/start HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
      "Detach": false,
@@ -2578,6 +2587,7 @@ Create a volume
 
     POST /v1.21/volumes/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "Name": "tardis"
@@ -2802,6 +2812,7 @@ Create a network
 ```
 POST /v1.21/networks/create HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Name":"isolated_nw",
@@ -2865,6 +2876,7 @@ Connect a container to a network
 ```
 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4"
@@ -2896,6 +2908,7 @@ Disconnect a container from a network
 ```
 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4"

docs/api/v1.22.md

@@ -23,6 +23,10 @@ redirect_from:
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.
+ - When the client API version is newer than the daemon's, these calls return an HTTP
+   `400 Bad Request` error message.
+ - A `Content-Length` header should be present in `POST` requests to endpoints
+   that expect a body.
 
 ## 2. Endpoints
 
@@ -220,6 +224,7 @@ Create a container
 
     POST /v1.22/containers/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
            "Hostname": "",
@@ -1387,6 +1392,7 @@ Copy files or folders of container `id`
 
     POST /v1.22/containers/4fa6e0f0c678/copy HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Resource": "test.txt"
@@ -2146,6 +2152,7 @@ Get the default username and email
 
     POST /v1.22/auth HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "username": "hannibal",
@@ -2315,6 +2322,7 @@ Create a new image from a container's changes
 
     POST /v1.22/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Hostname": "",
@@ -2647,6 +2655,7 @@ See the [image tarball format](#image-tarball-format) for more details.
 
     POST /v1.22/images/load
     Content-Type: application/x-tar
+    Content-Length: 12345
 
     Tarball in body
 
@@ -2690,6 +2699,7 @@ Sets up an exec instance in a running container `id`
 
     POST /v1.22/containers/e90e34656806/exec HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "AttachStdin": true,
@@ -2746,6 +2756,7 @@ interactive session with the `exec` command.
 
     POST /v1.22/exec/e90e34656806/start HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
      "Detach": false,
@@ -2891,6 +2902,7 @@ Create a volume
 
     POST /v1.22/volumes/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "Name": "tardis"
@@ -3123,6 +3135,7 @@ Create a network
 ```
 POST /v1.22/networks/create HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Name":"isolated_nw",
@@ -3195,6 +3208,7 @@ Connect a container to a network
 ```
 POST /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4",
@@ -3232,6 +3246,7 @@ Disconnect a container from a network
 ```
 POST /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4",

docs/api/v1.23.md

@@ -25,6 +25,8 @@ redirect_from:
    `stdin` and `stderr`.
  - When the client API version is newer than the daemon's, these calls return an HTTP
    `400 Bad Request` error message.
+ - A `Content-Length` header should be present in `POST` requests to endpoints
+   that expect a body.
 
 ## 2. Endpoints
 
@@ -244,6 +246,7 @@ Create a container
 
     POST /v1.23/containers/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
            "Hostname": "",
@@ -1128,6 +1131,7 @@ Update configuration of one or more containers.
 
        POST /v1.23/containers/e90e34656806/update HTTP/1.1
        Content-Type: application/json
+       Content-Length: 12345
 
        {
          "BlkioWeight": 300,
@@ -1422,6 +1426,7 @@ Copy files or folders of container `id`
 
     POST /v1.23/containers/4fa6e0f0c678/copy HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Resource": "test.txt"
@@ -2190,6 +2195,7 @@ if available, for accessing the registry without password.
 
     POST /v1.23/auth HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "username": "hannibal",
@@ -2365,6 +2371,7 @@ Create a new image from a container's changes
 
     POST /v1.23/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Hostname": "",
@@ -2697,6 +2704,7 @@ See the [image tarball format](#image-tarball-format) for more details.
 
     POST /v1.23/images/load
     Content-Type: application/x-tar
+    Content-Length: 12345
 
     Tarball in body
 
@@ -2766,6 +2774,7 @@ Sets up an exec instance in a running container `id`
 
     POST /v1.23/containers/e90e34656806/exec HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "AttachStdin": true,
@@ -2822,6 +2831,7 @@ interactive session with the `exec` command.
 
     POST /v1.23/exec/e90e34656806/start HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
      "Detach": false,
@@ -2967,6 +2977,7 @@ Create a volume
 
     POST /v1.23/volumes/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "Name": "tardis",
@@ -3224,6 +3235,7 @@ Create a network
 ```
 POST /v1.23/networks/create HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Name":"isolated_nw",
@@ -3312,6 +3324,7 @@ Connect a container to a network
 ```
 POST /v1.23/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4",
@@ -3349,6 +3362,7 @@ Disconnect a container from a network
 ```
 POST /v1.23/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4",

docs/api/v1.24.md

@@ -23,6 +23,8 @@ redirect_from:
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.
+ - A `Content-Length` header should be present in `POST` requests to endpoints
+   that expect a body.
 
 ## 2. Errors
 
@@ -253,6 +255,7 @@ Create a container
 
     POST /v1.24/containers/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
            "Hostname": "",
@@ -1172,6 +1175,7 @@ Update configuration of one or more containers.
 
        POST /v1.24/containers/e90e34656806/update HTTP/1.1
        Content-Type: application/json
+       Content-Length: 12345
 
        {
          "BlkioWeight": 300,
@@ -2208,6 +2212,7 @@ if available, for accessing the registry without password.
 
     POST /v1.24/auth HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "username": "hannibal",
@@ -2387,6 +2392,7 @@ Create a new image from a container's changes
 
     POST /v1.24/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
          "Hostname": "",
@@ -2725,6 +2731,7 @@ See the [image tarball format](#image-tarball-format) for more details.
 
     POST /v1.24/images/load
     Content-Type: application/x-tar
+    Content-Length: 12345
 
     Tarball in body
 
@@ -2794,6 +2801,7 @@ Sets up an exec instance in a running container `id`
 
     POST /v1.24/containers/e90e34656806/exec HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "AttachStdin": true,
@@ -2850,6 +2858,7 @@ interactive session with the `exec` command.
 
     POST /v1.24/exec/e90e34656806/start HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
      "Detach": false,
@@ -3000,6 +3009,7 @@ Create a volume
 
     POST /v1.24/volumes/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "Name": "tardis",
@@ -3290,6 +3300,7 @@ Create a network
 ```
 POST /v1.24/networks/create HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Name":"isolated_nw",
@@ -3379,6 +3390,7 @@ Connect a container to a network
 ```
 POST /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4",
@@ -3417,6 +3429,7 @@ Disconnect a container from a network
 ```
 POST /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
 Content-Type: application/json
+Content-Length: 12345
 
 {
   "Container":"3613f73ba0e4",
@@ -4130,6 +4143,7 @@ an empty value or the default cluster-wide value.
 
     POST /v1.24/nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "Availability": "active",
@@ -4231,6 +4245,7 @@ Initialize a new swarm. The body of the HTTP response includes the node ID.
 
     POST /v1.24/swarm/init HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "ListenAddr": "0.0.0.0:2377",
@@ -4377,6 +4392,7 @@ Update a swarm
 **Example request**:
 
     POST /v1.24/swarm/update HTTP/1.1
+    Content-Length: 12345
 
     {
       "Name": "default",
@@ -4576,6 +4592,7 @@ image](#create-an-image) section for more details.
 
     POST /v1.24/services/create HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "Name": "web",
@@ -4876,6 +4893,7 @@ image](#create-an-image) section for more details.
 
     POST /v1.24/services/1cb4dnqcyx6m66g2t538x3rxha/update?version=23 HTTP/1.1
     Content-Type: application/json
+    Content-Length: 12345
 
     {
       "Name": "top",