Subject: Last Call feedback on draft-ietf-tzdist-service-08

From: Mark Nottingham <[email-masked]>
Date: Wed, 17 Jun 2015 13:54:44 +1000

Regarding <https://tools.ietf.org/html/draft-ietf-tzdist-service-08> -

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.

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

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

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.

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.

4. More generally, I only found out about this draft because I happen to be the expert on one of the relevant registries, and got a ping from IANA. I'd expect that if we're working on standards that use HTTP, the HTTP WG would be notified and asked to review — especially since we have a history of using the protocol pretty poorly.

Cheers,

--
Mark Nottingham   https://www.mnot.net/

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 17 Jun 2015 10:44:00 -0400

Hi Mark,

--On June 17, 2015 at 1:54:44 PM +1000 Mark Nottingham <[email-masked]> 
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

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 22 Jun 2015 12:40:28 +1000

> On 18 Jun 2015, at 12:44 am, Cyrus Daboo <[email-masked]> wrote:
>> 
> 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.

We should be progressing it very soon; I have one dangling issue.

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

Ah - so you're effectively using SRV and/or .well-known as a DHCP-ish mechanism. I'm not against that in principle, but it needs to be spelled out; e.g., do I look in the domain that DHCP returns, or .local, or both, or…?

Cheers,