POST and ETag header

[danielwertheim]

When performing a POST to store a new document, there are no ETag headers returned. For PUT there is. Docs says there should be: http://docs.couchdb.org/en/2.0.0/api/database/common.html#post--db

[wohali]

Confirmed:

 $ curl --verbose -X POST -H "Content-Type: application/json" http://127.0.0.1:15984/foo -d '{"am":"joan"}'
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 15984 (#0)
> POST /foo HTTP/1.1
> User-Agent: curl/7.38.0
> Host: 127.0.0.1:15984
> Accept: */*
> Content-Type: application/json
> Content-Length: 13
>
* upload completely sent off: 13 out of 13 bytes
< HTTP/1.1 201 Created
< Cache-Control: must-revalidate
< Content-Length: 95
< Content-Type: application/json
< Date: Mon, 26 Jun 2017 19:45:42 GMT
< Location: http://127.0.0.1:15984/foo/263cad76416a130feb97e26cb400084a
* Server CouchDB/2.1.0-3559b7f (Erlang OTP/17) is not blacklisted
< Server: CouchDB/2.1.0-3559b7f (Erlang OTP/17)
< X-Couch-Request-ID: acdbe8171b
< X-CouchDB-Body-Time: 0
<
{"ok":true,"id":"263cad76416a130feb97e26cb400084a","rev":"1-c29e0faaccb770dc8964a43d22825195"}
* Connection #0 to host 127.0.0.1 left intact
$ curl --verbose -X PUT -H "Content-Type: application/json" http://127.0.0.1:15984/foo/bar -d '{"bread":"makes you fat"}'
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 15984 (#0)
> PUT /foo/bar HTTP/1.1
> User-Agent: curl/7.38.0
> Host: 127.0.0.1:15984
> Accept: */*
> Content-Type: application/json
> Content-Length: 25
>
* upload completely sent off: 25 out of 25 bytes
< HTTP/1.1 201 Created
< Cache-Control: must-revalidate
< Content-Length: 66
< Content-Type: application/json
< Date: Mon, 26 Jun 2017 19:46:36 GMT
< ETag: "1-4cd6186966b5c93e45a3f878d6029f67"
< Location: http://127.0.0.1:15984/foo/bar
* Server CouchDB/2.1.0-3559b7f (Erlang OTP/17) is not blacklisted
< Server: CouchDB/2.1.0-3559b7f (Erlang OTP/17)
< X-Couch-Request-ID: cdbe78e97c
< X-CouchDB-Body-Time: 0
<
{"ok":true,"id":"bar","rev":"1-4cd6186966b5c93e45a3f878d6029f67"}
* Connection #0 to host 127.0.0.1 left intact

[rnewson]

I think the docs are at fault here. I don't think it's right to return an ETag header from POST /dbname as the etag is related to the /dbname/newdocid resource not the /dbname resource.

[rnewson]

and further noting that the point of ETag response is for caching, and ~nothing caches POST responses (and for good reason).

[rnewson]

citing https://tools.ietf.org/html/rfc7231#section-7.2 as my basis for this claim.

In a successful response to a state-changing request, validator
fields describe the new representation that has replaced the prior
selected representation as a result of processing the request.

clearly the thing represented by /dbname was not replaced by the request body (a document) posted to it.

[wohali]

That may be true, but we did it in 1.6:

$ curl -X PUT http://127.0.0.1:5984/foo
{"ok":true}
$ curl --verbose -X POST -H "Content-Type: application/json" http://127.0.0.1:5984/foo -d '{"am":"joan"}'
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
> POST /foo HTTP/1.1
> User-Agent: curl/7.38.0
> Host: 127.0.0.1:5984
> Accept: */*
> Content-Type: application/json
> Content-Length: 13
>
* upload completely sent off: 13 out of 13 bytes
< HTTP/1.1 201 Created
* Server CouchDB/1.6.2 (Erlang OTP/17) is not blacklisted
< Server: CouchDB/1.6.2 (Erlang OTP/17)
< Location: http://127.0.0.1:5984/foo/c39513ad5ec7439a9880855224000da0
< ETag: "1-08055301094689837203c2862ea2bfe2"
< Date: Tue, 04 Jul 2017 15:44:47 GMT
< Content-Type: text/plain; charset=utf-8
< Content-Length: 95
< Cache-Control: must-revalidate
<
{"ok":true,"id":"c39513ad5ec7439a9880855224000da0","rev":"1-08055301094689837203c2862ea2bfe2"}
* Connection #0 to host 127.0.0.1 left intact

[rnewson]

I was trying to build 1.6.1 this last hour, without success, to see if this was a regression, so thanks for that.

[rnewson]

apache/couchdb-documentation#139

[wohali]

I'm closing this one as "works as designed" assuming that apache/couchdb-documentation#139 will hit in the next day or two.