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

[Julian Reschke <[e-mail]>]

Hi Andy,

thanks for the feedback. Replies inline.

On 2012-05-17 16:50, Andy Newton wrote:
> ...
>> a) I would be very careful in using "RESTful" when your intent essentially is only but using HTTP properly. In particular, the document seems to be silent on how the client actually discovers the URI it can send requests to (or alternatively, in case the URIs essentially are hardwired, that definition is missing).
>
> The purpose of talking about RESTful styling is that the group has decided to head in that direction, instead of doing something like SOAP over HTTP. Perhaps there is context missing here that can only be found in the other drafts.
>
> As for discovery, are you talking about service discovery or something simpler like URI templates?

Aha, so you're not there yet :-)

Using URI templates sound promising.

>> 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".

>>    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).

>> 4.2.  Parameters
>>
>>    To overcome issues with misbehaving HTTP [RFC2616] cache
>>    infrastructure, clients may use the '__weirds__cachebust' query
>>    parameter with a random value of their choosing.  Servers MUST ignore
>>    this query parameter.
>>
>>    The following is an example use of this parameter to retreive the
>>    abuse contacts associated with the most specific IP network with the
>>    address 192.0.2.0:
>>
>>
>>      /ip/192.0.2.0/operator/contacts/abuse?__weirds_cachebust=xyz123
>>
>>
>>    For all others, servers SHOULD ignore unknown query parameters.
>>
>> I think what you're saying is that all query parameters are ignored, right?
>>
>> The whole concept of reserving a specific one is strange to say the least.
>
> I don't know if it is strange, but I see your point. We simply need to state that all query unknown parameters should be ignored and the problem takes care of itself.

Yep.

I'd also move the discussion of cache busting into an appendix, or not 
mention it at all; it's not specific to this protocol.

>> 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.

>>    ...
>>
>> 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).

>>    8.  Common Error Response Body
>>
>>    As specified in Section 5, some non-answer responses may return
>>    entity bodies with information that could be more descriptive.
>>
>>    The basic structure of that response is a data class containing an
>>    error code number (corresponding to the HTTP response code) followed
>>    by a string named "title" followed by an array of strings named
>>    "description".
>>
>>    This is an example of the JSON version of the common response body.
>>
>>
>>      {
>>        "errorCode": 418
>>        "title": "No More Tacos",
>>        "description": [
>>          "We ran out of shells and sauce.",
>>          "Come back tomorrow." ]
>>      }
>>
>> That doesn't seem to be a good example of<http://tools.ietf.org/html/rfc2324#section-2.3.2>  :-)
>
> right. Let me fix that
> {
>    "errorCode": 418,
>    "title": "Your beverage choice is not available",
>    "description": [
>      "I know coffee has more ummppphhh.",
>      "But I cannot provide." ]
> }

Thanks :-) Larry will be happy.

> ...

Best regards, Julian