Opened 5 years ago

Closed 4 years ago

#29 closed defect (fixed)

URL design

Reported by: mglt.ietf@… Owned by: draft-ietf-tzdist-service@…
Priority: major Milestone:
Component: service Version:
Severity: Active WG Document Keywords:
Cc:

Description

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.

Change History (3)

comment:1 Changed 4 years ago by lear@…

  • Component changed from caldav-timezone-ref to service
  • Owner changed from draft-ietf-tzdist-caldav-timezone-ref@… to draft-ietf-tzdist-service@…
  • Severity changed from - to Active WG Document

comment:2 Changed 4 years ago by lear@…

Cyrus: it's a little bit of a nuisance to do this but not impossible. need to change version numbers.
Ken: No big deal to make a transition
Mike: we have got existing deployments, and I will support both formats.

Interim meeting agreed on general approach. Stephen will provide textual changes.

comment:3 Changed 4 years ago by lear@…

  • Resolution set to fixed
  • Status changed from new to closed

This is in the latest version. To be closed.

Note: See TracTickets for help on using tickets.