From bcdf9199006cf5e1027ad35981c70f3bea3159df Mon Sep 17 00:00:00 2001 From: Dietrich Schulten Date: Sun, 4 May 2014 12:42:21 +0200 Subject: [PATCH] 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. --- proposals/uber-templates-mca.asciidoc | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/proposals/uber-templates-mca.asciidoc b/proposals/uber-templates-mca.asciidoc index 88e98a5..9fe07c4 100644 --- a/proposals/uber-templates-mca.asciidoc +++ b/proposals/uber-templates-mca.asciidoc @@ -67,7 +67,13 @@ The +url+ property MAY contain a URI Template. Client applications MUST treat th ---- === Change the +model+ Property -The +model+ property only describes at payload (not a URL). If a client application sees a +model+ property, the client MUST use that as a guide for creating a payload. The +model+ still uses RFC570 (URI Template). +The +model+ property defines expected field names contained in a payload of the default type x-www-form-urlencoded by listing the valid names to include into the request body. If a client application sees a +model+ property, the client MUST use that as a guide for creating a payload. The +model+ no longer uses RFC570 (URI Template), but is only a list of names. + +If a +model+ property is present, a possible template MUST NOT contain a body property. + +If the mime type of the request is not x-www-form-urlencoded but +sending+ defines other structured data formats, there SHOULD be templates available for all mimetypes defined by the +sending+ property. + +In the XML variant the list of field names appears as a space-separated list. In the JSON variant the list of media-type identifiers appears as an array. .The +model+ property is applies only to the body ---- @@ -75,7 +81,7 @@ The +model+ property only describes at payload (not a URL). If a client applicat Mike Amundsen