Clarify the utility of base64-encoding of whole payloads or multipart parts

[handrews]

As seen in recent PR comments with @ralfhandl and @baywet, and in an earlier thread I started on the HTTP APIs Slack, base64-encoding an entire payload, or an entire part in a multipart payload, doesn't make much sense in HTTP.

Encoding binary to text as standardized in RFC 2045 Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies and revised and expanded in RFC 4648 The Base16, Base32, and Base64 Data Encodings was designed for email systems that often restricted bodies to 7-bit ASCII data. One of RFC 4648's revisions was to remove the line length restrictions on encoded data in RFC 2045, but the RFC still targeted environments with a 7-bit ASCII limitation. The MIME Content-Transfer-Encoding header indicated the use of such encoding.

HTTP does not have a 7-bit ASCII limitation on message bodies. Encoding binary data into ASCII expands it by 33% to 300% (although compressing the result complicates the calcuations).

In 2015, RFC 7578 Returning Values from Forms: multipart/form-data replaced RFC 2388 and deprecated the Content-Transfer-Encoding header in HTTP usage as it is not needed and no active use of it had been seen in the wild. It is still allowed in MIME.

I would suggest that we do the following in 3.0.4 and 3.1.1:

• Note that there are no HTTP headers which communicate base64 or similar encoding for an entire message payload, and that because of that and the data size increase, attempting such a thing is NOT RECOMMENDED
• Reference RFC 7578 §4.7's deprecation of Content-Transfer-Encoding in multipart/form-data and note that attempting to use an Encoding Object to induce it is unlikely to be supported by relevant software
• Note that other multipart media types have not deprecated Content-Transfer-Encoding, but it is still unnecessary in the context of HTTP
• Either remove examples of things that are NOT RECOMMENDED or add comments to the examples indicating that.

I'm guessing this probably needs some sort of @OAI/tsc approval.

Somewhat related: #1544 notes that format: binary doesn't make sense everywhere either.

[handrews]

PR merged for 3.0.4, with equivalent PRs merged for 3.1.1 and 3.2.0 - closing!