[apps-discuss] Review of draft-ietf-appsawg-uri-get-off-my-lawn

Tim Bray <tbray@textuality.com> Fri, 06 December 2013 06:22 UTC

MIME-Version: 1.0
Date: Thu, 05 Dec 2013 22:22:07 -0800
Message-ID: <CAHBU6it8+wVK6Mm3gppD-M_0YT03DgEbL82f777DUy1qMtncvA@mail.gmail.com>
From: Tim Bray <tbray@textuality.com>
To: "apps-discuss@ietf.org" <apps-discuss@ietf.org>
Content-Type: multipart/alternative; boundary="001a11c1e7fc684ad404ecd7aa03"
Subject: [apps-discuss] Review of draft-ietf-appsawg-uri-get-off-my-lawn
Precedence: list

I think this should be published as a Best Common Practice soon as possible.

Minor issues:

* The title and introduction:

“Standardising Structure in URIs“ is unfortunate because the central
message is “Don’t try to standardize structure in URIs”. How about
“Preserving URI Space Design Freedom” or “URI Structure Design Considered
Harmful” or “URI Space Design Ownership” - I think that last one is a
serious suggestion.

: This document cautions against this practice in standards (sometimes
called "URI Squatting").

I’m not sure the “sometimes called” parenthetical really adds value, but if
preserved, it should be moved to immediately after “this practice”. Also,
the document doesn’t caution against it, it bristles with MUST NOTs.  How
about “This document is intended to prevent the use of this practice
(sometimes called "URI Squatting") in standards.”

* 1. Introduction

The bullet point beginning “Dilution” is grammatically strained.  The
“extra information” is the subject of both verbs, so turn it around to read
something like “Extra information, added to URIs to support
standardization, dilutes their usefulness as ..., and causes alternate
forms of the URI to exist.  And I’m not sure Dilution is the right label;
the key point is weakening the URI’s utility as an identifier. Having said
that I can’t think of a one-word alternative.

In that list of bullet points, you might also want to add that query
parameters are problematic for two more reasons: There’s not a good hook in
3986 to use to say what you’re talking about, and also you’re doing a
parameter-name land-grab, which means you now have another design problem,
you have to prefix or otherwise clutter your parameter names to in effect
create a namespace for them.  Or worse, don’t.

2nd-last para:  The phrase that begins “publishing standards that mandate
URI structure is inappropriate... ” is the central tl;dr of this whole
draft, very nicely crystallized. Could it be pulled out and featured in the
introduction or even abstract?

* 2.

“Different components of a URI have differing practices recommended.”
Passive voice, turn it around: “Best practices differ depending on the URI
component”, or some such.

* 3.

I think you could just subtract this whole section and not much would be
lost. I think you’re trying to hint at HATEOS without actually naming it.
 In particular, I find the second paragraph entirely baffling, and have no
idea what it’s trying to say.

[apps-discuss] Review of draft-ietf-appsawg-uri-g… Tim Bray
Re: [apps-discuss] Review of draft-ietf-appsawg-u… Jan Algermissen
Re: [apps-discuss] Review of draft-ietf-appsawg-u… Erik Wilde
Re: [apps-discuss] Review of draft-ietf-appsawg-u… Paul Hoffman
Re: [apps-discuss] Review of draft-ietf-appsawg-u… Martin Thomson
Re: [apps-discuss] Review of draft-ietf-appsawg-u… Tim Bray
Re: [apps-discuss] Review of draft-ietf-appsawg-u… Mark Nottingham
Re: [apps-discuss] Review of draft-ietf-appsawg-u… Mark Nottingham