Subject: [Tzdist] RESTful URL design

From: Stephen Colebourne <[email-masked]>
Date: Sat, 27 Sep 2014 12:01:29 +0100

I have finally taken the time to read the URL aspects of the spec, and
I am extremely concerned about the proposed URL design. I do not think
that the design could be considered RESTful in the slightest, and as
such is against the best principles of the web.

There are many web pages available about the principles of RESTful
design for the web, and the ensuing benefits (of which caching is only
one). For the RESTful approach, you first identify your key
*resources* and then design URLs around those. In this case, the whole
data for a single TimeZone is clearly the primary resource.

GET /?action={action}

The use of action strings is bad practice and there are much better
alternatives.

GET /?action=capabilities
should be
GET /capabilities

GET /?format={format}
should use standard field in the request header

GET /?lang={lang}
should use standard field in the request header
(I note that multiple language parameters are allowed, but consider
that dubious)

GET /?action=list
should be a real URL, for example
GET /ids

GET /?action=get&tzid=America/New_York
should be a real URL, for example
GET /ids/America%2FNew_York

GET /?action=get&tzid=America/New_York
           &truncate=2010-01-01T00:00:00Z,2019-12-31T11:11:59Z
should be a real URL with query, for example
GET /ids/America%2FNew_York?truncateStart=2010-01-01T00:00:00Z&truncateEnd2019-12-31T11:11:59Z
(Note that a comma separated value is not good design IMO. If you
insist on one field it should follow the ISO-8601 standard using a
slash https://en.wikipedia.org/wiki/ISO_8601#Time_intervals)

GET /?action=expand&tzid=America/New_York
            &start=2008-01-01T00:00:00Z
           &end=2009-01-01T00:00:00Z
should be a real resource as it is conceptually different
GET /ids/America%2FNew_York/transitions?
           start=2008-01-01T00:00:00Z
           &end=2009-01-01T00:00:00Z

GET /?action=find&pattern=US/Eastern
should be a search/filter of the list resource
GET /ids?pattern=US/Eastern

In addition, the response JSON formats should be altered to contain
HATEOAS URLs, not just IDs.
       {
         "tzid": "America/New_York",
         "url": "/ids/America%2FNew_York"
         "last-modified": "2009-09-17T01:39:34Z",
         "aliases":["US/Eastern"],
       },

Making the changes above would bring the spec into conformance with
best practice web and REST design. Once done, there is the ability to
consider adding additional levels at the start to handle publishers
and versions as per

GET /publishers/{publisher}/versions/{version}/ids/...

This approach removes the need for "actions registry" and "parameter
registry", plus the separation of parameters from each action (the
spec defines parameters and actions separately, effectively creating a
cross reference of which parameters are valid for which action.

In my opinion, the changes above are required for the spec to be a
sensible valid member of the web community. While the providers can be
written to meet the current spec, such a web API would be highly
unfortunate for such an important set of data.

Note for example, that the current proposal allows for all these to be
the same (and 4 more, 8 in total)
GET /?action=get&tzid=America/New_York&format=text/calendar
GET /?action=get&format=text/calendar&tzid=America/New_York
GET /?tzid=America/New_York&format=text/calendar&action=get
GET /?tzid=America/New_York&action=get&format=text/calendar

Since there are multiple forms, most caching mechanisms will be highly
inefficient (and some will not work at all). Basically, an all query
mechanism forces web proxies to parse the URL to understand its
meaning to perform full featured caching (and other proxy behaviour).
Note that insisting on an order for query strings is not possible.

I'm sorry to be so negative about the spec, and I'm sorry I didn't
read it earlier, but it really does need a root and branch rethink to
be appropriate as a widely used internet standard.

Stephen

---

From: Tobias Conradi <[email-masked]>
Date: Sat, 27 Sep 2014 14:24:21 +0200

> GET /ids/America%2FNew_York

ids looks like plural, while only one ID is contained in the string.

> slash https://en.wikipedia.org/wiki/ISO_8601#Time_intervals)

ISO 8601 allows for
2010-01-01T00:00:00Z--2019-12-31T11:11:59Z

>            &end=2009-01-01T00:00:00Z

Why use "?" in the URL?

Why use two parameters for a range, and not as above the ISO 8601
interval notation?

> inefficient

One could recommend a standard order of the parameters to reduce variations.

-- 
Tobias Conradi
Rheinsberger Str. 18
10115 Berlin
Germany

http://tobiasconradi.com

---

From: Cyrus Daboo <[email-masked]>
Date: Mon, 29 Sep 2014 17:07:48 +0100

Hi Stephen,

> be appropriate as a widely used internet standard.

So first of all I removed the term "RESTful" from the spec (my working 
copy) a few days ago after a long debate by others on the IETF apps-disucss 
list about exactly what "REST" meant 
(<http://www.ietf.org/mail-archive/web/apps-discuss/current/msg12970.html>). 
It is quite clear that REST means different things to different people and 
is not necessarily the only way to design a web protocol (also recognizing 
that in our case we have more than just "web" clients accessing the data)

I don't want to get into an argument about best practices for web api 
design because it is trivial to find counter-arguments for many design 
choices, and I also don't consider myself an expert in that area either - 
at this point I would much rather defer to others on this issue so I do 
want to hear from the REST of the WG (pun intended).

-- 
Cyrus Daboo

---

From: Tobias Conradi <[email-masked]>
Date: Mon, 29 Sep 2014 19:32:40 +0200

On Mon, Sep 29, 2014 at 6:07 PM, Cyrus Daboo <[email-masked]> wrote:
> I don't want to get into an argument about best practices for web api design
> because it is trivial to find counter-arguments for many design choices, and
> I also don't consider myself an expert in that area either - at this point I
> would much rather defer to others on this issue so I do want to hear from
> the REST of the WG ...

1)
Stephen didn't address the issues pointed out in the first reply to
his proposal.

http://www.ietf.org/mail-archive/web/tzdist/current/msg00674.html

So these are either considered not to be issues or the proposal needs fixing.

Also the reasoning that avoiding different parameter orders which may
prevent caching are solved by his proposal has been shown to be
flawed.

2)
a) So there is a proposal using

http://example.com/tzdds/?param1=value1&param2=value2

Generation well supported by HTML forms.

b)
and Stephen's that replaces some similar to this:

http://example.com/tzdds/param1/value1?param2=value2

Then TZD servers need URLs parsing. For humans it might be hard to see
whether a string that could be either is a parameter name or a value

e.g.:
http://example.com/tzdds/publisher/atzdb/version/201/id/de/lang/id/

How would values that contain a "/" be written in such a path?

-- 
Tobias Conradi
Rheinsberger Str. 18
10115 Berlin
Germany

http://tobiasconradi.com

---

From: Daniel Migault <[email-masked]>
Date: Mon, 29 Sep 2014 21:29:55 +0200

Hi,

I agree with Cyrus, that the debate should not be whether we meet a RESTful
architecture or not. Given that, we would like to get feed back from the WG
on the URL format, we should adopt.

BR,
Daniel

On Mon, Sep 29, 2014 at 7:32 PM, Tobias Conradi <[email-masked]>
wrote:

> design
> _______________________________________________
> Tzdist mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tzdist
>

-- 
Daniel Migault
Orange Labs -- Security
+33 6 70 72 69 58

---

From: Lester Caine <[email-masked]>
Date: Mon, 29 Sep 2014 20:44:17 +0100

> How would values that contain a "/" be written in such a path?

This has always been my complaint about the TZ format of references.
Especially when there may be one or two extra '/' elements making url
parsing a problem.
This is where these elements get escaped, but that does not always
eliminate the problem.

-- 
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

---

From: Stephen Colebourne <[email-masked]>
Date: Mon, 29 Sep 2014 22:57:18 +0100

Daniel, Cyrus,
I do not overly care whether the phrase "RESTful" has meaning or not
as far as the spec is concerned. However, I do believe that there is
enough best practice out there to clearly say what is good and what is
not good in this field, focussed around the use of the features of
HTTP, including
- using GET/POST/PUT/DELETE (not relevant here)
- using HTTP headers for formats and languages where appropriate
- actions as resources (based on GET/POST/PUT/DELETE principles)
- queries for searches

Here is a high up Google link that I think captures the design
principles pretty well
http://codeplanet.io/principles-good-restful-api-design/

It is with this best practice that I find "?action=" to be just plain
wrong, especially when there is a clear and simple set of URL based
resources that can expose the functionality. (ie. this is not a
particularly difficult space in terms of resource design)

I'm happy to explain the detail of my original post, however I hope it
is fairly self-explanatory.

Stephen

---

From: Tobias Conradi <[email-masked]>
Date: Tue, 30 Sep 2014 00:33:48 +0200

On Mon, Sep 29, 2014 at 11:57 PM, Stephen Colebourne
<[email-masked]> wrote:

> I'm happy to explain the detail of my original post,
Not answering

http://www.ietf.org/mail-archive/web/tzdist/current/msg00677.html

indicates otherwise.

> however I hope it
It is not as has been shown.

-- 
Tobias Conradi
Rheinsberger Str. 18
10115 Berlin
Germany

http://tobiasconradi.com