Subject: [Tzdist] Issue #29 URL design

From: Stephen Colebourne <[email-masked]>
Date: Tue, 18 Nov 2014 13:13:05 +0000

http://trac.tools.ietf.org/wg/tzdist/trac/ticket/29

It may be wise to close the original issue and treat this feedback as
additional issues.

First, thanks for updating the spec and example server. It is good to
see the new structure in place. Here are the ensuing comments:

1) Language lookup
The spec includes examples with localized names and suggests that the
HTTP request will obtain the data, however the URL does not appear to
contain any elements that define the language (cf 5.2.1).

The original proposal was to use the "Accept-Language" header:
http://www.w3.org/International/questions/qa-accept-lang-locales

An alternative is to separate locale lookup entirely:
 {/service-prefix,data-prefix}/locale
 {/service-prefix,data-prefix}/locale/{localeId}
where the former provides a list of languages and the latter provides
a response for a single language (mapping all known zone ids to
localized text)

A final alternative is to carry on with the former use of "locale" as
a query parameter for this purpose.

2) Encoding
The spec does not appear to tackle the issue of encoding an identifier
like "America/New_York", specifically whether the slash should be
encoded or not. The examples do encode the slash. Perhaps section
4.1's discussion of encoding covers this - if so, then perhaps it
needs to be more explicitly called out with an appropriate slash
encoding example.

3) Listing observances
The original proposal called for a listing operation on observances:
 {/service-prefix,data-prefix}/observances

While in most cases, this would be the same as
 {/service-prefix,data-prefix}/zones
there might be cases where they differ.

If zone identifiers are to be encoded AND there is no desire for a
separate listing action for observances, then this approach probably
makes more sense:
 {/service-prefix,data-prefix}/zones/{tzid}/observances

4) Actions
The spec and capabilities response talk about "actions", but there is
no direct way to link an action to a URL without reading the spec.

Adding a URL to the capabilities section response would be helpful here:

"actions": [
    {
      "name": "list",
      "url": "/zones",
      "parameters": [
        {
          "name": "changedsince"
        }
      ]
    },

5) URLs in list/find responses
The response to the list and find actions would benefit from having a
URL for each zone. Without this, clients are forced to build up the
URLs themselves:

   GET /zones HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Wed, 4 Jun 2008 09:32:12 GMT
   Content-Type: application/json; charset="utf-8"
   Content-Length: xxxx

   {
     "dtstamp": "2009-10-11T09:32:11Z",
     "timezones": [
       {
         "tzid": "America/New_York",
         "url": "/zones/America%2FNew_York",
        "last-modified": "2009-09-17T01:39:34Z",
         "aliases":["US/Eastern"],
         "local-names": [
           {
             "name": "America/New_York",
             "lang": "en_US"
           }
         ]
       },
       ...
     ]
   }

Note that including the URL also allows the encoding of the slash in
the zone identifier to be done by the server, avoiding client
mistakes.

Thanks again for the updates so far.
Stephen

---

From: Ken Murchison <[email-masked]>
Date: Tue, 18 Nov 2014 09:48:46 -0500

Hi Stephen,

>   {/service-prefix,data-prefix}/zones/{tzid}/observances

I might make an argument that observances are just the zone data in 
another format, rather than a [collection of] sub-resource within the 
zone.  In fact, I use the same code to both expand a zone and truncate a 
zone.  Given that fetching of the zone already allows for start and end 
query parameters, I think an approach like this might make sense:

{/service-prefix,data-prefix}/zones{/tzid}{?expand,start,end}

where the 'expand' query parameter is a boolean defaulting to false.

-- 
Kenneth Murchison
Principal Systems Software Engineer
Carnegie Mellon University

---

From: Cyrus Daboo <[email-masked]>
Date: Tue, 18 Nov 2014 10:30:26 -0500

Hi Stephen,

> a query parameter for this purpose.

I will go with an Accept-Language header approach since that should be 
"automatic" for existing HTTP servers. I've added a new section to 4.1 to 
cover that (we already have a section in there describing Accept header 
behavior).

> needs to be more explicitly called out with an appropriate slash

The requirement to encode the {/tzid} variable in the URI template is 
required by the URI template spec itself (see Section 3.2.6 of RFC6570). 
However, given the preponderance of "/" in tzids it does make sense to call 
that out. I have added text to section 4.1 to cover that.

>  {/service-prefix,data-prefix}/zones/{tzid}/observances

I think I will follow up on Ken's reply to this point as this deserves some 
careful discussion.

> no direct way to link an action to a URL without reading the spec.

Well I do want implementors to read the spec!

> Adding a URL to the capabilities section response would be helpful here:

Will comment on this as part of the next issue.

> the zone identifier to be done by the server, avoiding client

Well I have seen cases where WebDAV used a DAV:href XML element with a 
%-encoded value that the client then turned around a re-encoded!

My goal for using URI templates was to avoid the need to repeat the same 
URI pattern for each time zone data entry and instead just allow clients to 
support a templating mechanism that took care of the encoding issues all in 
one place. I would still like to avoid including the URL in at least the 
"list" action response if possible.

For the capabilities response, one thing that did not get described fully 
was how the server might advertise additional URI segments (as per the 
discussion on publisher ids and versions). I think we probably need a 
section in capabilities that does define which {/data-prefix} values are 
supported by the server, so clients can quickly see those if the server 
supports them.

-- 
Cyrus Daboo

---

From: Cyrus Daboo <[email-masked]>
Date: Tue, 18 Nov 2014 10:37:07 -0500

Hi Ken,

> where the 'expand' query parameter is a boolean defaulting to false.

That is probably OK, but one tricky aspect is that the end value is 
inclusive for the get (truncation range) but exclusive for the expand. I 
don't like the idea of having those differ based solely on the expand 
parameter. Also, one other point to note is that the expand action does 
make use of a changedsince parameter, but if we dovetail it on to the get 
action, then it makes much more sense to drop that in favor of normal HTTP 
conditional request behavior (i.e., ETag + If-None-Match).

-- 
Cyrus Daboo

---

From: Tim Parenti <[email-masked]>
Date: Thu, 20 Nov 2014 00:29:07 -0500

On 18 November 2014 10:30, Cyrus Daboo <[email-masked]> wrote:

> 2) Encoding [...]

+1

4) Actions
>  Adding a URL to the capabilities section response would be helpful here:
+1

Going back briefly to one old comment about publisher names, which I
believe would be part of the data-prefix template specified in §4.1
<http://tools.ietf.org/html/draft-ietf-tzdist-service-03#section-4.1>…

On 28 October 2014 05:09, Clive D.W. Feather <[email-masked]> wrote:

> It would seem reasonable to reserve all strings beginning "iana".

It seems to me that we should be clearer about whether we intend our
protocol to dictate namespacing for this.  (This is distinct from the
problem posed in §3.5
<http://tools.ietf.org/html/draft-ietf-tzdist-service-03#section-3.5> which
states that time zone identifier namespacing is out of our scope.)  I'm
inclined to lean toward the side that this is also outside our scope, but
given IETF's relation to IANA and RFC 6557
<https://tools.ietf.org/html/rfc6557>, maybe not.

--
Tim Parenti

---

From: Tim Parenti <[email-masked]>
Date: Thu, 20 Nov 2014 00:43:09 -0500

On 18 November 2014 10:37, Cyrus Daboo <[email-masked]> wrote:

> one tricky aspect is that the end value is inclusive for the get
> (truncation range) but exclusive for the expand

Must it be the case that these are different?  A while back, I raised the
point that ideally these wouldn't be different at
http://www.ietf.org/mail-archive/web/tzdist/current/msg00625.html.  (The
rest of that thread is mostly irrelevant now.)

Looking back, it seems we're treating TZUNTIL as inclusive so as not to
have to exceed the 32-bit time_t range to get the full 32-bit data (
http://www.ietf.org/mail-archive/web/tzdist/current/msg00470.html).  And,
if I had to make an educated guess, it seems the expand bound is exclusive
to allow for easy concatenation of multiple result sets.  How important
would this be in practice?  What else could we gain by simplifying this,
and is it worth the cost?

--
Tim Parenti

---

From: Stephen Colebourne <[email-masked]>
Date: Thu, 20 Nov 2014 12:41:30 +0000

On 18 November 2014 15:30, Cyrus Daboo <[email-masked]> wrote:
> My goal for using URI templates was to avoid the need to repeat the same URI
> pattern for each time zone data entry and instead just allow clients to

Why? Response size issues?
Right now, the caller of the list/find has to know how to build up the
URL of the get, rather than being told. (Being told allows the URL to
be completely different, such as a versioned URL, which gives
significant extra potential power.

{
         "url": "providers/iana/versions/2014f/zones/America%2FNew_York",

>> where the 'expand' query parameter is a boolean defaulting to false.

This is one choice, although not my preferred one. It depends on
whether people think it is conceptually the same data in a different
format, or related data. In general though, these changes have been
about getting away from using a query parameter to control the data
returned (only using query params for filtering).

Stephen

---

From: Ken Murchison <[email-masked]>
Date: Thu, 20 Nov 2014 07:53:05 -0500

>           "aliases":["US/Eastern"],

Why couldn't a template for the URLs be placed in the top-level list 
object, rather than enumerating them for each time zone?

Or as I think Cyrus mentioned, perhaps the URL templates for each action 
belong in the capabilities response.

---

From: Stephen Colebourne <[email-masked]>
Date: Thu, 20 Nov 2014 14:10:22 +0000

On 20 November 2014 12:53, Ken Murchison <[email-masked]> wrote:
> Why couldn't a template for the URLs be placed in the top-level list object,
> rather than enumerating them for each time zone?

Doing so is a lot better than not having any URL links at all. It just
makes the clients life a little harder.

Stephen