POST request payload, format, and behavior are not clearly specified

[philipashlock]

It's not clear if the example of json data for POST /magazines/[id]/articles is the payload sent as the POST request or if its the response from a successful POST request, or both. Typical POST requests with an HTML webform are sent as application/x-www-form-urlencoded and that is specified in the header. I'm guessing the example shown is sent as json, but that should be clarified. If these guidelines are agnostic about how POST requests are made in the same way they're agnostic about xml or json responses, then perhaps it should discuss how people can know the options available. Perhaps specifying the format as an extension in the URL is used not only to indicate the response format, but also the payload being sent in the request.