Allow for payload media types to be documented about spec HOT 5 CLOSED

Not to be repetitive (I know when all you have is a hammer - everything can look like a nail - but I have solved a great many problems using the built in header capabilities of HTTP, and have always wanted to extend them to message processing. - I hope that you find this feedback both constructive, well-intentioned, and helpful. )

The RFC for HTTP [RFC 7231] includes a specification for "Content Negotiation" between the request agent and the response agent. Encapsulating a method of communication of preferred request and response metadata could solve a lot of not yet anticipated future problems.

5.3. Content Negotiation

The following request header fields are sent by a user agent to
engage in proactive negotiation of the response content, as defined
in Section 3.4.1. The preferences sent in these fields apply to any
content in the response, including representations of the target
resource, representations of error or processing status, and
potentially even the miscellaneous text strings that might appear
within the protocol.

+-------------------+---------------+
| Header Field Name | Defined in... |
+-------------------+---------------+
| Accept | Section 5.3.2 |
| Accept-Charset | Section 5.3.3 |
| Accept-Encoding | Section 5.3.4 |
| Accept-Language | Section 5.3.5 |
+-------------------+---------------+

5.3.2. Accept

The "Accept" header field can be used by user agents to specify response media types that are acceptable.

3.1.1.5. Content-Type

The "Content-Type" header field indicates the media type of the associated representation

So: Accept indicates what kind of response from the server the client can accept. Content-type always is about the content of the current request or response.

So if your request has no payload, you don't use a content-type request header.

from spec.

That's a great idea. Thanks for the feedback! I'm marking it for version 2.0.0.

from spec.

Wouldnt it be better to place such a notice inside the header information? I made a quick'n dirty demonstration here:

If it looks good to you, I recommend adding it to the example. I would also add an example that sends or receives a simple text (text/plain) instead of json. The online editor does support this as well, which is super awesome to have json and plaintext API documentation in the same place.

Here is a screenshot of a pure text payload (please add this as sample, but with some better names/description):

BTW: Did you look into Mqtt5 yet? It provides some additional features such as sending the content type (mime + utf8 yes/no), user properties aka. utf8 string-pairs, retained messages TTL and more.

I was about to create a feature request for those new features, but it seems it can be realized with the headers section, which is also the best place to put this information. Opinions?

from spec.

Placing a header can also have other undesired consequences, for instance, it can make a system fail if it doesn't support the mime-type header.

Headers are part of the message as payload is. Content type should be documented in a different way. Also, it would help message portability, allowing you to use the same message with different formats, e.g., JSON and XML.

from spec.

🎉 This issue has been resolved in version 1.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

from spec.