Subject: [T2TRG] draft-keranen-t2trg-rest-iot-01: URI Semantics

From: "Simpson, Robby (GE Energy Connections)" <[email-masked]>
Date: Tue, 22 Mar 2016 21:08:15 +0000

Hi,

In reading draft-keranen-t2trg-rest-iot-01 I note the following:

>> The path is hierarchical; the query is non-hierarchical.

It is my understanding that this statement is subject to debate.

Certainly some RESTful APIs assign hierarchical semantics to the path.
For example, /foo may refer to a "collection-style" resource and /foo/bar
may refer to a resource within that collection.

However, is this a necessary requirement?  From my perspective, this could
potentially limit extensibility as future revisions of a RESTful API may,
for instance, wish to insert a resource "between" /foo and /foo/bar.  If
the resources themselves are truly self-describing, containing links to
"subordinate" resources, then the path portion of the URI can become an
opaque identifier and backward compatibility in this hypothetical RESTful
API could be maintained.

Likewise, I have seen RESTful APIs where the order of the elements in the
query portion of the URI matters (particularly if a given element occurs
multiple times).

I would suggest staying silent on the semantics of these parts of the URI
or noting that they MAY be hierarchical / non-hierarchical.

Thanks,
Robby

---

From: Ari Keränen <[email-masked]>
Date: Fri, 25 Mar 2016 19:37:12 +0000

Hi Robby,

Thanks for the feedback! See below.

> On 22 Mar 2016, at 14:08, Simpson, Robby (GE Energy Connections) <[email-masked]> wrote:
> 
> Hi,
> 

True; the path part is often referred to as "the hierarchical" part, but indeed it does not always need to be so.

However, the query part is specifically referred to as "non-hierarchical" in RFC3986 so I think we should keep those semantics. I know that e.g. some libraries do not preserve the order so one should not rely on that working.

So, I'd suggest to change that part into:
"The path is often hierarchical; the query is non-hierarchical."

And perhaps add a note in the end of the last paragraph along the lines of: 
"The query parameter order is not always preserved (e.g., due to URI normalization) and hence should not be relied upon".

Cheers,
Ari

---

From: "Kovatsch Matthias" <[email-masked]>
Date: Mon, 28 Mar 2016 13:30:33 +0000

Hi

The point is that the order of the path segments matters; the order of the query parameters  does not. Changing the order of the paths would give you a different URI. The query parameters can be mutated. Thus caches need a way to normalize URIs, that is, build their cache key.

I assume Robby is referring to the fact that correlated paths say nothing about the relation of two resources (which I wouldn't say is subject to debate, but widely misunderstood). A client MUST NOT assume that removing a path segment will lead to a parent resource. Resources with less path segments may even be nonexistent, that is, lead to a 404/4.04. The relation between two resources can only be reasoned about through Web links that were published by (or on behalf) of the server (e.g., rel="next", rel="prev", or rel="up" which would mean going up in a hierarchy of resources).

How a resource path is constructed is fully up to the origin server, or rather to the developers/operators of the server. They can put a lot of logic in organizing their resources, group related items together in the same "folder" etc. The client, however, may not reason about this structure. Machine will not be able to this. It only works for us humans, that we can delete parts of a URI in the browser to get to the place we want to go. That is not because URIs are meant that way, but because we are fellow humans who are able to guess how the developers organized their server namespace.

Ciao
Matthias

> -----Original Message-----
> From: T2TRG [mailto:[email-masked]] On Behalf Of Ari Keränen
> Sent: Friday, 25 March 2016 20:37
> To: Simpson, Robby (GE Energy Connections) <[email-masked]>
> Cc: [email-masked]
> Subject: Re: [T2TRG] draft-keranen-t2trg-rest-iot-01: URI Semantics
> 
> Hi Robby,
> 
> > For example, /foo may refer to a "collection-style" resource and
> > /foo/bar may refer to a resource within that collection.
> >
> > However, is this a necessary requirement?  From my perspective, this
> > could potentially limit extensibility as future revisions of a RESTful
> > API may, for instance, wish to insert a resource "between" /foo and
> > /foo/bar.  If the resources themselves are truly self-describing,
> > containing links to "subordinate" resources, then the path portion of
> > the URI can become an opaque identifier and backward compatibility in
> > this hypothetical RESTful API could be maintained.
> >
> > Likewise, I have seen RESTful APIs where the order of the elements in
> > the query portion of the URI matters (particularly if a given element
> > occurs multiple times).
> >
> > I would suggest staying silent on the semantics of these parts of the
> > URI or noting that they MAY be hierarchical / non-hierarchical.
> 
> However, the query part is specifically referred to as "non-hierarchical" in
> RFC3986 so I think we should keep those semantics. I know that e.g. some
> libraries do not preserve the order so one should not rely on that working.
> 
> "The query parameter order is not always preserved (e.g., due to URI
> normalization) and hence should not be relied upon".
> 
> 
> Cheers,
> Ari
> _______________________________________________
> T2TRG mailing list
> [email-masked]
> https://www.irtf.org/mailman/listinfo/t2trg

---

From: "Subramaniam, Ravi" <[email-masked]>
Date: Mon, 28 Mar 2016 14:58:21 +0000

Hi,

+1 with Robby - there is no value in describing the path as "hierarchical" - it is limiting without adding any value. Also agree that it should be opaque to the recipient and agree with Mathias that no information on structure should be assumed in the 'path'.

I agree with Mathias that "order of the path segments matter"  and that relation between resources are discovered with web links. 

In OCF, we use both these statements - the 'path' is called out as a segmented name (so order is still important). Recipients are required to treat this as opaque. We also require structure to be described and discovered using links. (Another benefit here is use of hashes - if 'path' is a name i.e. handle then the hash of a name is also a handle. But if the 'path' is defined as a hierarchical structure i.e. a locator then hash of the 'path' loses or masks this structure).

Thanks!

Ravi

-----Original Message-----
From: T2TRG [mailto:[email-masked]] On Behalf Of Kovatsch Matthias
Sent: Monday, March 28, 2016 6:31 AM
To: Ari Keränen <[email-masked]>; Simpson, Robby (GE Energy Connections) <[email-masked]>
Cc: [email-masked]
Subject: Re: [T2TRG] draft-keranen-t2trg-rest-iot-01: URI Semantics

Hi

Ciao
Matthias

> > could potentially limit extensibility as future revisions of a 
> > RESTful API may, for instance, wish to insert a resource "between" 
> > /foo and /foo/bar.  If the resources themselves are truly 
> > self-describing, containing links to "subordinate" resources, then 
> > the path portion of the URI can become an opaque identifier and 
> > backward compatibility in this hypothetical RESTful API could be maintained.
> >
> > Likewise, I have seen RESTful APIs where the order of the elements 
> > in the query portion of the URI matters (particularly if a given 
> > element occurs multiple times).
> >
> > I would suggest staying silent on the semantics of these parts of 
> > the URI or noting that they MAY be hierarchical / non-hierarchical.
> 
> True; the path part is often referred to as "the hierarchical" part, 
> but indeed it does not always need to be so.
> 
> RFC3986 so I think we should keep those semantics. I know that e.g. 
> some libraries do not preserve the order so one should not rely on that working.
>

---

From: Dave Thaler <[email-masked]>
Date: Mon, 28 Mar 2016 19:29:26 +0000

RFC 3986 and RFC 6943 (sections 3.3.3 and 3.3.4 among others) both discuss this.
Although it is unspecified whether order actually matters in a given query,
in a generic URI parser and comparator, such as is used in caches, etc., the
order matters in the path and in the query.  That's because
"comparison methods are designed to minimize false negatives while strictly avoiding false
positives."

So if you change the order, it's a different URI.   The result may be the same,
and it's quite legal to have multiple URIs for the same content/resource.
But that doesn't change the fact that it's a different URI as far as caching,
security tickets, etc. go.

See RFC 6943 for more discussion.

Dave

> From: T2TRG [mailto:[email-masked]] On Behalf Of Subramaniam,
> Ravi
> Sent: Monday, March 28, 2016 7:58 AM
> To: Kovatsch Matthias <[email-masked]>; Ari Keränen
> <[email-masked]>; Simpson, Robby (GE Energy Connections)
> <[email-masked]>
> Cc: [email-masked]
> +1 with Robby - there is no value in describing the path as "hierarchical" - it is
> limiting without adding any value. Also agree that it should be opaque to the
> recipient and agree with Mathias that no information on structure should be
> assumed in the 'path'.
> 
> I agree with Mathias that "order of the path segments matter"  and that
> relation between resources are discovered with web links.
> 
> In OCF, we use both these statements - the 'path' is called out as a
> segmented name (so order is still important). Recipients are required to treat
> this as opaque. We also require structure to be described and discovered
> using links. (Another benefit here is use of hashes - if 'path' is a name i.e.
> handle then the hash of a name is also a handle. But if the 'path' is defined as
> a hierarchical structure i.e. a locator then hash of the 'path' loses or masks
> this structure).
> 
> Thanks!
> 
> Ravi
> 
> The point is that the order of the path segments matters; the order of the
> query parameters  does not. Changing the order of the paths would give you
> a different URI. The query parameters can be mutated. Thus caches need a
> way to normalize URIs, that is, build their cache key.
> 
> I assume Robby is referring to the fact that correlated paths say nothing
> about the relation of two resources (which I wouldn't say is subject to
> debate, but widely misunderstood). A client MUST NOT assume that
> removing a path segment will lead to a parent resource. Resources with less
> path segments may even be nonexistent, that is, lead to a 404/4.04. The
> relation between two resources can only be reasoned about through Web
> links that were published by (or on behalf) of the server (e.g., rel="next",
> rel="prev", or rel="up" which would mean going up in a hierarchy of
> resources).
> 
> How a resource path is constructed is fully up to the origin server, or rather to
> the developers/operators of the server. They can put a lot of logic in
> organizing their resources, group related items together in the same "folder"
> etc. The client, however, may not reason about this structure. Machine will
> not be able to this. It only works for us humans, that we can delete parts of a
> URI in the browser to get to the place we want to go. That is not because
> URIs are meant that way, but because we are fellow humans who are able to
> guess how the developers organized their server namespace.
> 
> Ciao
> Matthias
> 
> https://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fwww.i
> >
> rtf.org%2fmailman%2flistinfo%2ft2trg&data=01%7c01%7cdthaler%40microso
> f
> >
> t.com%7c484c2f85428b4919f47408d35719c264%7c72f988bf86f141af91ab2d7c
> d01
> >
> 1db47%7c1&sdata=yUA0clweBOM%2fQLzgMiVE2McvKbcIdS%2b81jJOARNpy
> rU%3d
> 
> https://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fwww.ir
> tf.org%2fmailman%2flistinfo%2ft2trg&data=01%7c01%7cdthaler%40microsof
> t.com%7c484c2f85428b4919f47408d35719c264%7c72f988bf86f141af91ab2d7c
> d011db47%7c1&sdata=yUA0clweBOM%2fQLzgMiVE2McvKbcIdS%2b81jJOAR
> NpyrU%3d
> 
> https://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fwww.ir
> tf.org%2fmailman%2flistinfo%2ft2trg&data=01%7c01%7cdthaler%40microsof
> t.com%7c484c2f85428b4919f47408d35719c264%7c72f988bf86f141af91ab2d7c
> d011db47%7c1&sdata=yUA0clweBOM%2fQLzgMiVE2McvKbcIdS%2b81jJOAR
> NpyrU%3d

---

From: Ari Keränen <[email-masked]>
Date: Fri, 1 Apr 2016 02:40:01 +0000

OK, so it seems the best way forward is to drop the "The path is hierarchical; the query is non-hierarchical" part from the draft text completely. Then, add note about query parameters potentially being re-ordered and point to RFC6943 for more details about the impact of ordered query part in the last paragraph of section 3.4 (https://tools.ietf.org/html/draft-keranen-t2trg-rest-iot-01#section-3.4).

Sounds good?

Cheers,
Ari

> On 28 Mar 2016, at 16:29, Dave Thaler <[email-masked]> wrote:
>