Currently, the REST framework supports both "post" and "body" as PARAM_SOURCE values returned by getParamSettings. Thy behave similarly, but not identically:
"post" parameters:
* support //form data// requests bodies, but not JSON request bodies
* are accessible through getValidatedParams, but not getValidatedBody
* do not support complex values (arrays), but do support multi-value
"body" parameters:
* support both //form data// requests bodies as well as JSON request bodies
* are not accessible through getValidatedParams, but through getValidatedBody
* do support complex values (arrays) as well as multi-value
This is somehwat confusing, especially if they are mixed. We should try to clarify this situation.
== Proposal ==
# Do not allow "post" and "body" parameters to be mixed. A handler can only use one of these two kinds of param sources.
# Do not support //form data// requests if "body" is used.
# Allow "post" params to function with JSON requests
# Potentially, we might introduce a getBodyParamSettings method, to allow body fields and path params to have overlapping names.
This way, endpoints that only need simple data from POST requests can opt into supporting form-data (in addition to JSON) by using "post" parameters. Such endpoints would handle body fields just like query parameters, which is typical for HTML form handling.
This however means that no complex fields can be added, not even optionally. Handlers that want to support complex data in the request body (now or in the future) would use "body" parameters. Such handlers would require a JSON body (or a custom implementation of parseBodyData), and would use getValidatedBody to access the request data.