Document response body negotiation for PUT and POST requests via Accept header

[mjustin]

When doing some integration testing, I discovered the hard way that unless configured otherwise, PUT & POST only return a response body when the HTTP Accept header is set (due to #418). My regular calls apparently set the headers but it took me some time, digging through code, and some web searching to figure out why my integration test was not seeing a response body.

Looking into the reference guide, I see almost no mention of this behavior. The only reference is in 4.1.2. Default Status Codes, where it refers to the status code (but not the response body):

If the configuration values (RepositoryRestConfiguration.returnBodyOnUpdate and RepositoryRestConfiguration.returnBodyCreate) are explicitly set to null, the presence of the HTTP Accept header is used to determine the response code.

I think it would be beneficial if the response body behavior were more explicitly documented. In particular, it would be helpful if the reference guide called out that the presence of a response body is dependent on the accept header unless configured otherwise.

Incidentally, I think this Stack Overflow user likewise ended up getting bitten by this exact same piece of behavior, so I don't think it's just me who's had to track down this mostly undocumented behavior.

[odrotbohm]

Can you elaborate on which other parts of the documentation you have looked for in hope of finding information? I am a bit puzzled because you quote a section from the reference documentation that describes the behavior and in the immediate next sentence ask for that behavior to be mentioned in the docs. Which you have just quoted. In the paragraph before.

That said, I assume it's rather a matter of discoverability. I can see that we might mention this behavior in the general documentation of the resources we expose (POST would go here, PUT would go here). I'll also take the chance to polish up the Javadocs for RepositoryRestConfiguration to make sure it's obvious that the already described behavior for setting null is actually also the default behavior. Happy to learn about other parts of the docs that could benefit from a pointer.

[odrotbohm]

Re-reading the docs paragraph, I assume there's a catch: the current wording creates the assumption that as a user, you'd have to explicitly enable that by configuring the relevant methods on RepositoryRestConfiguration to get that behavior. What's missing is that it's the default in the first place because the initial values are null in the first place.

[mjustin]

Can you elaborate on which other parts of the documentation you have looked for in hope of finding information?

For this particular search, I was mostly looking through this reference guide. I was observing the behavior, and wanted to see if it was actually documented somewhere.

I am a bit puzzled because you quote a section from the reference documentation that describes the behavior and in the immediate next sentence ask for that behavior to be mentioned in the docs. Which you have just quoted. In the paragraph before.

If you'll note, the quoted paragraph states nothing about the response body, just about the response status code. One could probably guess that it's likely that such a request conditionally returns a body or not based on the presence of the HTTP header (since why else would it be using different response codes), though as far as I can tell, it's not outright stated in the documentation.

So in other words, while the documentation section tells the reader what happens to the status code of a response based on whether the Accept header is present, it makes no mention of what happens to the body of the response.

As a side note, on reread of the whole section, it looks like only PUT/PATCH/DELETE behavior is called out (in the 204 No Content default status code section). It's not stated how POST behaves.

That said, I assume it's rather a matter of discoverability.

That's a pretty big part of it, yeah. It's not straightforward to discover this, especially if you're thinking in terms of response bodies and not response status codes. Also, having a quotable section of the documentation makes it easier to answer other peoples' issues related to this, since the quoted section can be referenced directly.

Thanks!

[odrotbohm]

That's all tremendously helpful. Thanks a lot! I'll get to it ASAP.

[odrotbohm]

I've pushed a fix in 6d19e96. If you have further ideas, what could be clarified, feel free to comment.