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

[Julian Reschke <[e-mail]>]

Hi there,

it would be great if the boilerplate did specify the discussion venue 
(this would have avoided one roundtrip to the authors :-).

That being said: see comments inline.


1.  Introduction

    ...

    This document describes the usage of HTTP for Internet registry Whois
    services running on RESTful web servers for the purposes of
    addressing the deficiencies as described above.  The goal of this
    document is to tie together the usage patterns of HTTP into a common
    profile applicable to the various types of Internet registries
    serving Whois data using RESTful styling.  By giving the various
    Internet registries a common behavior, a single client is better able
    to retreive data from Internet registries adhering to this behavior.

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

b) s/retreive/retrieve/

    The goal of this specification is to define a simple use of HTTP to
    deliver Whois information using RESTful patterns.  Where complexity
    may reside, it is the goal of this specification to place it upon the
    server and to keep the client as simple as possible.  In the
    vacubulary of computer programmers, it should be suffecient enough to

s/vacubulary/vocabulary/
s/suffecient/sufficient/

    write a client for this application in bash using commands such as
    wget or curl and other commonly available command line tools.

    This is the basic usage pattern for this protocol:

    1.  A client issues an HTTP query using GET.  As an example, a query

s/query/request/

        for the network registration 192.168.0.0 might be
        http://example.com/ip/192.168.0.0.

    2.  If the receiving server has the information for the query, it
        examines the Accept header of the query and returns a 200
        response with a response entity appropriate for the requested
        format.

    3.  If the receiving server does not have the information for the
        query but does have knowledge of where the information can be
        found, it will return a response of 301 or 303 with the Redirect
        header containing an HTTP URL pointing to the information.  The
        client is expected to re-query using that HTTP URL.

s/header/header field/

It's also not clear why it needs to be 301 or 303 here.

    ...

3.  Design Intents

    There are a few design criteria this document attempts to support.

    First, each query is meant to return either zero or one result.  With
    the maximum upper bound being set to one, the issuance of redirects
    is simplified to the known document model used by HTTP [RFC2616].

Document model?

    ...


4.  Queries

4.1.  Accept Header

    Clients SHOULD put the MIME type of the format they desire in the

a) Why is this a SHOULD? What's the impact of not doing so?

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.

    Clients may use a generic MIME type for the desired data format of
    the response, but servers MUST respond with the most appropriate MIME
    type.  In other words, a client may use "application\json" to express

s|application\json|application/json| (throughout the documemt)

    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?

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.

    ...

5.  Types of HTTP Response

   ...

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.

    A server should use a 301 response to inform the client of a
    permanent move and a 303 repsonse otherwise.  For this application,

This makes it sound as if it should be 302, not 303. It's also not 
clears why 307 (and maybe 308) aren't mentioned here.

s/repsonse/response(

    such an example of a permentant move might be a TLD operator

s/permentant/permanent/

    informing a client the information being sought can be found with
    another TLD operator (i.e. a query for the domain bar in foo.example
    is found at http://foo.example/domain/bar)

   ...

5.4.  Malformed Queries

    If a server receives a query which it cannot understand, it SHOULD
    return a 503 response code.  Optionally, it may include additional
    information about why it does not understand the query as defined by
    Section 8.

If the problem is the request than the status code should be a 4xx.

    ...

6.2.  Naming

    JSON names SHOULD only consist of the alphabetic ASCII characters A
    through Z in both uppercase and lowercase, underscore characters, and
    SHOULD NOT begin with an underscore character or the characters
    "xml".  This restriction is a union of the Ruby programming language
    identifier syntax and the XML element name syntax and has two
    purposes.  First, client implementers using modern programming
    languages such as Ruby or Java may use libraries that automatically
    promote JSON values to first order object attributes or members (e.g.
    using the example above, the values may be referenced as
    network.handle or network.lunarNic_beforeOneSmallStep).  Second, a
    clean mapping between JSON and XML is easy to accomplish using the
    JSON representation.

I think ABNF would be good here, even if the XML prefix exclusion be 
just in prose.

Also: no digits???

    ...

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

    ...


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

    The MIME type for the JSON structure is
    "application\weirds_common_error_v1+json" and the MIME type for the
    XML document is "application\weirds_common_error_v1+xml".

Are you going to register these with IANA?

    A client MAY simply use the HTTP response code as the server is not
    required to include error data in the response body.  However, if a
    client wishes to parse the error data, it SHOULD first check that the
    Accept header contains the appropriate MIME type.

s/Accept/Content-Type/


Best regards, Julian