Subject: [art] Last Call for Comments: draft-nottingham-rfc7320bis (BCP 190 update)

From: Adam Roach <[email-masked]>
Date: Tue, 15 Oct 2019 18:54:52 -0500

ART community (cc DISPATCH and HTTPBIS, but please respond only to ART):

Based on conversations on the DISPATCH and ART mailing lists this past 
summer [1], and on in-person discussions that took place in Montreal, 
Mark Nottingham has produced a revision of BCP 190 that takes into 
account community input on several points. The changes are all intended 
to be relaxations of previously-enforced restrictions on how URI 
namespaces could be used.

The revised document is at:

https://datatracker.ietf.org/doc/draft-nottingham-rfc7320bis/

And diffs from the current, in-force version of BCP 190 can be seen here:

https://www.ietf.org/rfcdiff?url1=rfc7320&url2=draft-nottingham-rfc7320bis-02

This message is intended to serve as a final, two-week last call for 
input from the ART community before the document is put forth for formal 
IETF consensus. The final consensus document will be published as a 
replacement of RFC 7320 (formally, it will obsolete it), and will become 
the new BCP 190.

Please provide input on the document on the ART mailing list 
([email-masked]) by Wednesday, October 30th. To prevent the conversation 
from becoming fragmented, please do not respond to the HTTPBIS or 
DISPATCH mailing lists on this topic.

Thanks!

/a

____
[1] 
https://mailarchive.ietf.org/arch/search/?q=bcp%20190&f_list=art%2Cdispatch

---

From: Stephen Farrell <[email-masked]>
Date: Wed, 16 Oct 2019 13:44:37 +0100

Hiya,

> DISPATCH mailing lists on this topic.

I only had time for a quick scan but that looks like a good
improvement, thanks.

One suggestion, if the Mark (or someone else) had the time
and inclination: it could be good to include a short paragraph
describing an example of when it was ok to diverge from the
general guidance and (briefly) why. Maybe trans would provide
that example. I don't think adding that is necessary, but
it'd help I think.

Cheers,
S.

---

From: Larry Masinter <[email-masked]>
Date: Wed, 16 Oct 2019 12:10:44 -0700

On 8/21/2019 at 7:50 AM I wrote

An update to BCP 190 should take into account the fact that there is not a consensus for the "best" of various "current practice" for avoiding the URL squatting identified (namely using a hypermedia format to let the server control the URL format completely rather than the API control the URL syntax and making the client do string processing.

But didn't see a reply.  

If you want links, link to draft-hartke-t2trg-coral and draft-kelly-json-hal as two examples of current practice for which the "best" way hasn't shaken out.

Larry
--
https://LarryMasinter.net

-----Original Message-----
From: Larry Masinter <[email-masked]> On Behalf Of Larry Masinter
Sent: Wednesday, August 21, 2019 7:50 AM
To: 'Adam Roach' <[email-masked]>; 'John C Klensin' <[email-masked]>; 'Mark Nottingham' <[email-masked]>
Cc: 'Jacob Hoffman-Andrews' <[email-masked]>; 'Devon O'Brien' <[email-masked]>; 'ART Area' <[email-masked]>
Subject: RE: [art] Call for Consensus: Re: On BCP 190

Just back from an August vacation, apologies for brevity IMHO An update to BCP 190 should take into account the fact that there is not a consensus for the "best" of various "current practice" for avoiding the URL squatting identified (namely using a hypermedia format to let the server control the URL format completely rather than the API control the URL syntax and making the client do string processing.

As far as process goes, I think it's ok to drop the DISCUSS in
 question because it is Experimental and not Standards track.

As  Carsten Bormann <[email-masked]> wrote  Sunday, July 28, 2019 1:43 AM
Re: [art] On BCP 190

> 
> On Jul 28, 2019, at 08:26, Larry Masinter <[email-masked]> wrote:
> >
> > Now, why JSON-HAL is still an expired  Internet Draft is a puzzle.
> 
> (Slightly, but not completely off-topic:)
> 
> Probably because there are multiple ways to skin this cat and we never 
> tried to converge on one.
> 
> As a data point, for the applications in the CoRE working group, we 
> have mostly been able to avoid BCP190-style arguments by using 
> /.well-known, mainly because simple devices only tend to have one 
> service offered directly under / and because IoT device platforms tend 
> to provide the application developer full control over the URI space.  
> /.well-known/core provides a discovery mechanism for the entry point URIs
actually offered by a server.
> 
> For where this is not enough, the WG has just last week adopted CoRAL 
> (not yet resubmitted as draft-ietf, so you can find it at 
> draft-hartke-t2trg-coral) as our idea of a hypermedia format like HAL.  
> Up to now, we tried to make everything work with RFC 6690 link format, 
> but that has too many idiosyncrasies that started to get in the way of a
long-term way forward.

---

From: Adam Roach <[email-masked]>
Date: Wed, 16 Oct 2019 18:33:28 -0500

Thanks for bringing that up again, Larry! I recall seeing that message 
and having a hard time parsing out the point you were making or deducing 
what resultant changes you'd like to see to BCP 190. I meant to return 
to it later to puzzle out your exact meaning, but it got away from me. I 
apologize.

Thanks for adding concrete examples; looking to them for clarification...

It appears that draft-kelly-json-hal is using URIs exactly as expected 
(that is, the _thing_ being talked about is exactly the _thing_ the URI 
has been assigned to by the site administrator), albeit with some 
interesting HTTP-specific protocol stuff that uses Content-Type to 
change the response body from information to metainformation. There's 
certainly some HTTP-related discussion to be had here about the wisdom 
of overloading the semantics of Content-Type in this way, but it doesn't 
seem to bear on the naming question. Correct me if I've simply found the 
wrong part of this document.

I dug through draft-ietf-core-coral and couldn't quite find any 
mechanism that seems to align with the words in your statement below. 
But then again, it's a pretty big draft, and you didn't cite any 
particular behavior in particular, so I might have missed the section 
you have in mind. For what its worth, the URI handling that I see in 
that document is based on the provisioning of a (server-controlled) 
starting-point URI into clients, and then using a document at that 
endpoint as a roadmap for all the other URIs used by the application. 
This seems entirely compliant with both BCP 190 as currently written and 
with the proposed BCP 190 currently under discussion. I see nothing to 
"take into account" here, as the draft's approach is already in 
accordance with BCP 190 (and, in fact, it was one of the solutions that 
I encourage TRANS to pursue).

As before, I'm trying not to take a position on any given issue here, so 
I don't intend to argue for or against the point you're making -- I'm 
just looking for clarity on what you're trying to say, ideally in a way 
that is understandable to the community and (assuming the community 
agrees) actionable for the draft author.

I would propose that the easiest way to make progress is to send 
concrete suggestions to this mailing list detailing text that you would 
like to see added/revised/removed from the current draft. If you find it 
easier, you may wish to submit a PR against 
https://github.com/mnot/I-D/blob/gh-pages/rfc7320bis/draft.md and post a 
link to that PR to this mailing list. If not, email with OLD/NEW 
sections would serve the purpose just fine.

Thanks!

/a

On 10/16/19 2:10 PM, Larry Masinter wrote:
> _______________________________________________
> art mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/art

---

From: Larry Masinter <[email-masked]>
Date: Wed, 16 Oct 2019 17:16:43 -0700

As I understand it, people wanting to do what used to be separate protocols
now define the network interface as a kind of REST API.

https://en.wikipedia.org/wiki/Hypertext_Application_Language

HAL is the name for a style of Interface where the relationship between one
resource and other resources that are related are not defined by asking the
client to do string manipulation on the URLs (like you might by defining a
base and doing relative relations) but rather explicitly returning
"hypermedia objects" that contain explicit URLs of the related resources.

JSON-HAL is just one such building block.  When I mentioned it on the ART
list, Carsten Bormann noted that the CoRE working group was going to adopt a
derivative called CoRAL.
 (draft-hartke-t2trg-coral-02 contained a note about JSON HAL that was
dropped in later versions.)

The reason for including any of this in rfc7320bis/BCP-190 is to point
people at this rather extensive body of work by people who were trying to
solve the problem that BCP-190 was set up to warn people away from. 
BCP-190 started as an internet draft "get off my lawn" but as is, it gives
scant advice for how to avoid the practice and still accomplish the goals.

It just seemed odd to update BCP 190 without giving more of a hint about
what seemed to be a widespread method of avoiding doing excessive and
unwieldy URL mangling in network protocols.

>> service offered directly under / and because IoT device platforms 
>> tend to provide the application developer full control over the URI
space.
>> /.well-known/core provides a discovery mechanism for the entry point 
>> URIs actually offered by a server.
>> Up to now, we tried to make everything work with RFC 6690 link 
>> format, but that has too many idiosyncrasies that started to get in 
>> the way of a long-term way forward.

https://it.toolbox.com/blogs/craigborysowich/overview-of-api-hypermedia-type
s-093018
https://www.fenews.co.uk/press-releases/33067-detailed-guide-api-technical-a
nd-data-standards-v2-2019

---

From: Adam Roach <[email-masked]>
Date: Thu, 17 Oct 2019 15:10:03 -0500

Ah, okay. So it sounds like you're suggesting that Section 3 should add 
new content to talk about additional techniques, beyond the three it 
already describes.

Can you propose some text?

/a