v3.1.2: Clarify how to describe no response content

[handrews]

Fixes #3536.

We decided that the lack of content doesn't guarantee a lack of response content, but that noting a Content-Length of 0 does. @karenetheridge pointed out that we can set the Content-Length header to clarify this.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[handrews]

I'm a little uncertain on this because the HTTP spec is very squirrelly around Content-Length, but it seems to be the best way to set expectations given the current options.

[karenetheridge]

"no return value" is not very clear (some might say a response's "return value" is its HTTP response code) -- we should say "with no message body", or perhaps "zero length response body".

[handrews]

@karenetheridge good catch- let me think on how to frame this more clearly.

[handrews]

@karenetheridge I'm starting to question this entire approach.

I know that we generally say that OADs are not comprehensive, and something that is not documented is not necessarily excluded (paging @mikekistler, @earth2marsh ).

But by this logic, having a Response Object that only documents application/json would also allow, say, application/xml. Or text/html. Which is a feature rather than a bug, as you might document some 400 responses with known JSON payloads, but an intermediary might send one back with a text/html response. This is not wrong exactly, but was also not anticipated (or anticipatable) by the API designer.

So I think that the original advice to just omit content should send just a clear of a signal that no content is expected as specifying application/json content only signals that XML, HTML, etc. are not expected.

And if that is the case, then I feel like getting into the use of Content-Length is getting too deep in the weeds. Particularly given that RFC9110 makes it clear that you can't rely on it (many no-content responses won't include Content-Length, but chunked responses don't include it either). People who really want to get detailed with Content-Length are likely people who can figure this out already. And it's a bit misleaing/confusing to everyone else. Maybe? I think?

I'm moving this to draft to indicate that I don't think it's ready for merge.

[karenetheridge]

Sure, leaving out content entirely sends the signal that the body is not important -- for documenting APIs for consumers, that's totally fine.

But what about server implementers, if they want to verify that there is definitely no message body? That's a valid usecase (at $lastjob, I built exactly such a thing into the test framework for a server application), and it would be nice for there to be a way to signal "if there is a message body, then this is invalid".

But yes, this doesn't have to go into the spec. I think we have an issue/discussion somewhere discussing a set of docs that would act as a cookbook? I might be thinking of JSON Schema.

[handrews]

@karenetheridge the use case is definitely valid! It's just that (as you note) this doesn't have to go in the spec to be usable, and the fact that Content-Length is not a sure-fire way to verify this has me thinking that it shouldn't. An article about interesting or non-obvious content modeling cases on the learn site would probably be a good thing, though.

To really enforce it, we'd need to add some sort of additional field, which would mean 3.2/3.3.

It sounds to me like you're OK with closing this, though? It is a 100% valid use case, I just don't think this is clear and reliable enough to go into the spec.

[handrews]

Closing in favor of OAI/learn.openapis.org#132.