Documenting POST parameters with WADL

Question

Looking at the current version of the WADL proposal, I couldn't quite figure out how to document POST request parameters (with application/x-www-form-urlencoded encoding).

I've seen something like this in the wild:

<resource path="/path1">
<!-- default is mediaType="application/x-www-form-urlencoded" -->
    <method name="POST">
        <request>
            <name="param1" style="query"/>
        </request>
    </method>
</resource>

However, for a <param style="query"> used as a child of <request>, the spec describes it as:

Specifies a URI query parameter represented according to the rules for the query component media type specified by the queryType attribute.

The "URI query" bit threw me off since, to me, it suggests parameters being appended to the URI instead of being included in the body.

On the other hand, for a <param style="query"> used as a child of <representation>, the spec has:

Specifies a component of the representation as a name value pair formatted according to the rules of the media type. Typically used with media type 'application/x-www-form-urlencoded' or 'multipart/form-data'.

Do I have to use a <representation> element to explicitly document parameters that will be send in encoding as part of a POST body?

<resource path="/path1">
    <method name="POST">
        <request>
            <representation mediaType="application/x-www-form-urlencoded">
                <name="param1" style="query"/>
            </representation>
        </request>
    </method>
</resource>

This looks like an overkill. I'm assuming I should be able to use the former, even though the spec makes mention of "URI query".

Answer 1

Now I see that I actually should be using the latter form. Even if it looks like an overkill for simply documenting some POST parameters, it's better to explicitly document the fact that the parameters are part of the body == representation.