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

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: weirds-bounces@ietf.org [mailto:weirds-bounces@ietf.org] On Behalf Of Andy Newton
Sent: donderdag 17 mei 2012 20:54
To: Julian Reschke
Cc: weirds@ietf.org
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
weirds@ietf.org
https://www.ietf.org/mailman/listinfo/weirds