Re: [weirds] feedback on draft-designteam-weirds-using-http

[Andy Newton <[e-mail]>]

Maarten,

Using media types for versioning RESTful interfaces has been quite common in the industry for years. I would hardly call it abusive. Here is an old post by Peter Williams on the subject: 
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Looking around though, it would seem that use the level extension is a way of using the Accept/Content-Type headers without encoding the version in the media type itself. See: 
http://techbits.blogspot.com/2012/02/versioning-restful-apis-there-seems-to.html

Though level is not explicitly specified in the Content-Type header definition, the syntax is legal as a parameter the same as it is specified in the Accept header. This seems like a decent approach.

-andy


On May 30, 2012, at 3:13 AM, Maarten Wullink wrote:

> I would suggest removing the versioning information from the content-type.
> Put the version information in the URL itself, like this where "v1" is the version 1 of the API.
> 
> /base/v1/domains/example.com
> 
> This way is clear what version of the API the client is connecting to and you do
> Not have to abuse the content-type for this.
> 
> For more about versioning see:
> http://blog.apigee.com/taglist/versioning
> 
> 
> application\weirds_blah_v1+json
> 
> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On Behalf Of Andy Newton
> Sent: donderdag 17 mei 2012 20:54
> To: Julian Reschke
> Cc: [e-mail]
> Subject: Re: [weirds] feedback on draft-designteam-weirds-using-http
> 
> 
> On May 17, 2012, at 12:00 PM, Julian Reschke wrote:
> 
>> Using URI templates sound promising.
> 
> This keeps coming up, but so far nobody has shown why it is useful. I think what we want out of URI templating is to be shown what utility it adds before placing it in the specifications.
> 
>>>> b) s/MIME type/media type/
>>>> 
>>>>  Accept header.  Servers SHOULD respond with an appropriate MIME type
>>>>  in the Accept header in accordance with the preference rules for the
>>>>  Accept header in HTTP [RFC2616].  However the use by clients of
>>>>  multiple MIME types in the Accept header is NOT RECOMMENDED.
>>>> 
>>>> It's not clear to me why you're profiling HTTP here.
>>> 
>>> Because for this application, clients will probably only know one format. The need to use the complex rules for specifying multiple formats is unnecessary.
>> 
>> I don't follow. Servers need to process the Accept header field according to RFC 2616. Are you saying they can rely on it being simpler? In which case, this would need to be a "MUST NOT".
> 
> Uh, yeah. I think I'm trying to have it both ways. It's probably best to simply remove this.
> 
>>>>  that it desires JSON or "application\weirds_blah_v1+json" to express
>>>>  that it desires WEIRDS BLAH version 1 in JSON.  The server MUST
>>>>  respond with "application\weirds_blah_v1+json".
>>>> 
>>>> This seems to invent a new concept of media ranges in content negotiation that didn't exist before. Why is this needed?
>>> 
>>> For signaling the version of the schema desired. Is there another method you feel is more appropriate?
>> 
>> The method is probably ok, but the way it was explained was confusing: client specifies it wants "A", but server is allowed to return "B" (and label it as "B"), if it has out-of-band info that the client will understand it, too. Note that here "A" and "B" could be any media type (the label is really opaque).
> 
> Ok. I'll look into cleaning this up.
> 
>> 
>>>> 5.2.  Redirects
>>>> 
>>>>  If a server wishes to inform a client that the answer to a given
>>>>  query can be found elsewhere, it should return either a 301 or a 303
>>>>  reponse code and an HTTP URL in the Redirect header.  The client is
>>>> 
>>>> s/reponse/response/
>>>> 
>>>>  expected to issue a subsequent query using the given URL without any
>>>>  processing of the URL.  In other words, the server is to hand back a
>>>>  complete URL and the client should not have to transform the URL to
>>>>  follow it.
>>>> 
>>>> HTTPbis allows relative URIs here, and so should this protocol.
>>> 
>>> Why? It is simpler for the clients if the URLs are absolute.
>> 
>> Do not profile the base protocol unless there is a very very good reason.
> 
> I now understand what you are saying.
> 
>>>>  ...
>>>> 
>>>> 7.  Use of XML
>>>> 
>>>> 7.1.  Signaling
>>>> 
>>>>  Clients may signal their desire for XML using the "application\xml"
>>>>  mime type or a more application specific XML mime type.
>>>> 
>>>> 7.2.  Naming and Structure
>>>> 
>>>>  Well-formed XML may be programmatically produced using the JSON
>>>>  encodings due to the JSON naming rules outlined in Section 6.2 and
>>>>  the following simple rules:
>>>> 
>>>>  1.  Where a JSON name is given, the corresponding XML element has the
>>>>      same name.
>>>> 
>>>>  2.  Where a JSON value is found, it is the content of the
>>>>      corresponding XML element.
>>>> 
>>>> That is not true for all JSON values (consider control characters).
>>> 
>>> Ah yes, the escaping needs to be changed from JSON to XML.
>> 
>> There's still a set of characters that won't be usable in XML (yes, not even escaped).
> 
> That would be &, <, and >. So I guess we should mention those are to be escaped as well. Gosh XML is overly complex.
> 
> 
> Thanks for the input.
> 
> -andy
> 
> _______________________________________________
> weirds mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/weirds
> _______________________________________________
> weirds mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/weirds