mamund/media-types — pull request #38 by dschulten (2014-05-04 10:42:32+00:00)
Title: Updated Proposed change to the model attribute

The model, template and sending attributes have a potential to contradict each other. Trying to sort out the interdependencies between these three, I want to propose this change. Even if this proposal is not accepted, I think the relationship between these three attributes needs to be explicitly clarified and I hope my (quite radical) proposal helps us to see which contradictions can happen :)

If I am not mistaken, the only UriTemplate which expresses a form-urlencoded POST body is a level 1 template in the form name={value}&name={value}. At least I see no higher level template which expands to a form-urlencoded request body. A model of {givenName, familyName, hatSize} does not expand to a form-urlencoded body but to "Mark, Foster, Medium". {?givenName, familyName, hatSize} expands to something with a leading '?' and {&givenName, familyName, hatSize} to something with a leading '&'.

But if the model would always have to write out a full form-urlencoded body with variables anyway, we do not gain much by the model attribute as a mini-template. What is really only needed are the field names which are expected by the server in a PUT or POST. So I would like to propose this change.

Another point for this is the mime type of a request which is built from the model attribute (here: form-urlencoded by default). If the model does not expand to form-urlencoded, the data item would have to say so in the sending attribute. To deviate from form-urlencoded would only work with something similarly simple like text/plain, more complex requests cannot really be templated by the model attribute but require a template body anyway. So why have a mini-template in model and a full-blown template at the same time?

So I would like to propose to restrict the model to be the field name list for form-urlencoded only. The template constraints can describe valid values for the field names, the template body is for advanced request types.