Hi Mark,
--On June 17, 2015 at 1:54:44 PM +1000 Mark Nottingham <mnot@xxxxxxxx>
wrote:
1. The draft uses URI templates to specify resources, but does so
statically in the specification, rather than allowing them to be
determined by the server. This doesn't violate the letter of BCP190, but
it doesn't honour the spirit of it; the server is not in control of its
own URI shape, except at the coarsest level (effectively, a prefix).
Much better would be to have the first request not return a redirect, but
instead a set of templates that tells the client how to find the
appropriate resources on the server.
Well the capabilities action does in fact do that, but you are right that
the definition of each action defines a fixed URI template. I think my
argument here is that this specification is for a protocol with a very
specific API - its not the same a a "looser" web-api. That is why we
require "Specification Required" for actions - we want implementers to go
read the specs and fully understand the semantics of exactly what the
action is and what parameters are required, rather than having to follow
links and figure out what the relation types are supposed to mean. Now that
may be my own personal preference for a "strongly defined" protocol as
opposed to a loosely defined webapp, but I believe it is warranted for this
use case.
The "actions" listed in section 5 would be more appropriately referred to
as resources — calling them "actions" cuts against the grain of the
entire Web architecture. They also are natural fits for having distinct
link relations (RFC5988).
I think "action" clearly indicates that this is the definition of an API as
opposed to the "structure" of a URI space. The spec does use the term
"resource" in several places, in particular in Section 4.1:
Each action targets a specific HTTP resource...
Note that this isn't an "I'm lying down in the road, this technology is
broken" comment — more of a "It would be so easy to get this right with
a bit of effort."
Understood.
2. Section 4.1.7 comes dangerously close to re-defining the semantics of
HTTP status codes, and should be removed.
E.g., 304 only happens in the context of a conditional request, but it is
not mentioned here. 400 does *not* have the semantics of "The Sender has
provided an invalid request parameter", and overloading them here is
inappropriate.
I am fine with deleting the list of status codes. We still need that
section to refer to the use of the JSON problem detail spec. As an aside:
since you are the author of the draft what is its status? Obviously the
tzdist spec references normatively so we would need your draft to progress
(ideally as soon as possible). If that is not likely to happen then we will
need to incorporate your JSON schema directly in our spec and drop the
reference.
3. Section 4.2 doesn't motivate why it's necessary to start with a
hostname to resolve the URI of the time zone distribution service, rather
than just start with the URI itself. What's the use case here? They're
both just strings.
Clients can be directly configured with a URI - that's fine. But Section
4.2 is mostly about the case where clients don't have any information about
available services and they need to find a suitable one. In the absence of
user input, clients can simply look for a service in their local domain.
Even in the case where user input is available, it is much easier to tell
the user to enter a domain or simply their "email address" and have
discovery work off that (with the added benefit of the indirection that SRV
lookups give). This is akin to discovering other "services" for a user such
as email and calendaring.
--
Cyrus Daboo