Remote API documentation doesn't mention that the "Content-Length" field is necessary in POST requests

[hpollinger]

Description of problem:
Neither the documentation itself nor the examples in the Remote API documentation (specifically for v1.20, https://docs.docker.com/reference/api/docker_remote_api_v1.20/ ) mention that the "Content-Length" field is necessary in all POST requests that have a body.
The value in this field is not exactly important, at least as it is larger or equal to the actual body size.

docker version:
Client:
Version: 1.8.2
API version: 1.20
Go version: go1.4.2
Git commit: 0a8c2e3
Built: Thu Sep 10 19:19:00 UTC 2015
OS/Arch: linux/amd64

Server:
Version: 1.8.2
API version: 1.20
Go version: go1.4.2
Git commit: 0a8c2e3
Built: Thu Sep 10 19:19:00 UTC 2015
OS/Arch: linux/amd64

docker info:
Containers: 98
Images: 9
Storage Driver: aufs
Root Dir: /var/lib/docker/aufs
Backing Filesystem: extfs
Dirs: 211
Dirperm1 Supported: false
Execution Driver: native-0.2
Logging Driver: json-file
Kernel Version: 3.13.0-63-generic
Operating System: Ubuntu 14.04.3 LTS
CPUs: 4
Total Memory: 7.664 GiB
Name: sirius.mydomain.test
ID: OKAA:4QF6:6QJ4:R4SE:IWFG:YJLY:PFFW:YTEK:URCB:MTCV:QCOY:VP3Y
WARNING: No swap limit support

uname -a:
Linux sirius.mydomain.test 3.13.0-63-generic #103-Ubuntu SMP Fri Aug 14 21:42:59 UTC 2015 x86_64 x86_64 x86_64 GNU/Linux

Environment details (AWS, VirtualBox, physical, etc.):
Physical

How reproducible:
Always

Steps to Reproduce:

1. Execute the following command line in the terminal
   $ echo -e "POST /containers/4d50a1065a88/copy HTTP/1.1\r\nContent-Type: application/json\r\n\r\n{\r\n"Resource": "test.txt"\r\n}\r\n" | sudo nc -U /var/run/docker.sock

Actual Results:
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
Server: Docker/1.8.2 (linux)
Date: Wed, 23 Sep 2015 08:35:54 GMT
Content-Length: 4

EOF
HTTP/1.1 400 Bad Request

Expected Results:
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
Server: Docker/1.8.2 (linux)
Date: Wed, 23 Sep 2015 08:39:53 GMT
Content-Length: 59

Could not find the file test.txt in container 4d50a1065a88

Additional info:
The expected result is printed with this command line:
$ echo -e "POST /containers/4d50a1065a88/copy HTTP/1.1\r\nContent-Type: application/json\r\nContent-Length: 1000\r\n\r\n{\r\n"Resource": "test.txt"\r\n}\r\n" | sudo nc -U /var/run/docker.sock

[phemmer]

That's because this is part of the http spec.

https://tools.ietf.org/html/rfc2616#section-4.4

For compatibility with HTTP/1.0 applications, HTTP/1.1 requests
containing a message-body MUST include a valid Content-Length header
field unless the server is known to be HTTP/1.1 compliant. If a
request contains a message-body and a Content-Length is not given,
the server SHOULD respond with 400 (bad request) if it cannot
determine the length of the message, or with 411 (length required) if
it wishes to insist on receiving a valid Content-Length.

[vdemeester]

As @phemmer said, it's part of the HTTP spec.

Closing.

[hpollinger]

What phemmer wrote does not relate to this doc bug report.

The examples are wrong. They don't work. It's not possible to copy&paste them and get the expected results.

Besides of this, the RemoteAPI documentation SHOULD point to the http spec. It could also mention that - in opposition to the http spec - the value of Content-Length may be larger than the actual length.

[vdemeester]

@hpollinger oh you're right, we should update documentation to make the copy/paste !! My bad 😓

[thaJeztah]

@hpollinger would you be interested in contributing, and opening a pull request with the changes you think are needed? The Markdown files used to generate the API documentation can be found in this repository; https://github.com/docker/docker/tree/master/docs/reference/api

[nwright-nz]

#dibs