Subject: [apps-discuss] RESTful definition

From: "Murray S. Kucherawy" <[email-masked]>
Date: Mon, 15 Sep 2014 13:15:28 -0700

Is there a sufficiently stable definition for "REST" or "RESTful" we can
reference from a future RFC?  I can't think of anything authoritative, and
search engines point me to things that I don't imagine we'd consider to be
stable enough.  Wikipedia seems to be the closest thing; do we allow such
references in RFCs these days?

Thanks,
-MSK

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 15 Sep 2014 22:18:06 +0200

On 15 Sep 2014, at 22:15, Murray S. Kucherawy <[email-masked]> wrote:

> Is there a sufficiently stable definition for "REST" or "RESTful" we can reference from a future RFC?  I can't think of anything authoritative, 

What’s wrong with Roy Fielding’s dissertation?
For RFC 7252, we used:

   [REST]     Fielding, R., "Architectural Styles and the Design of
              Network-based Software Architectures", Ph.D. Dissertation,
              University of California, Irvine, 2000,
              <http://www.ics.uci.edu/~fielding/pubs/dissertation/
              fielding_dissertation.pdf>.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Mon, 15 Sep 2014 22:24:18 +0200

Or <http://svn.tools.ietf.org/svn/wg/httpbis/specs/rfc7231.html#REST>:

> [REST]	Fielding, R., “Architectural Styles and the Design of Network-based Software Architectures”, Doctoral Dissertation, University of California, Irvine, September 2000, <http://roy.gbiv.com/pubs/dissertation/top.htm>.

Which is what we used in HTTP.

Best regards, Julian

---

From: Dave Crocker <[email-masked]>
Date: Mon, 15 Sep 2014 13:22:27 -0700

> What’s wrong with Roy Fielding’s dissertation?

A "definition" is usually relatively short, measured by a few sentences.

An entire book is rather too long to qualify.

A tight reference to a few sentences /in/ a book might be useful, of course.

It is also possible that, over the years, the industry has found some
concise wording to define the term that is better than what Roy came up
with for his dissertation.

d/
-- 
Dave Crocker
Brandenburg InternetWorking
bbiw.net

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 15 Sep 2014 22:31:34 +0200

> A "definition" is usually relatively short, measured by a few sentences.

Sure, “REST, short for Representational State Transfer, is an architectural style defined in [REST].”

I doubt one can capture the essence of REST in a few sentences.

(Unfortunately, the dissertation has some editorial issues that make it hard to extract that essence except through a number of careful readings.  That’s the stuff religions are made of... But exegesis is worth it in this case.)

Grüße, Carsten

---

From: Dave Crocker <[email-masked]>
Date: Mon, 15 Sep 2014 13:31:55 -0700

On 9/15/2014 1:31 PM, Carsten Bormann wrote:
> On 15 Sep 2014, at 22:22, Dave Crocker <[email-masked]> wrote:>> A "definition" is usually relatively short, measured by a few
>> sentences.
> 

That's almost certainly a problem.  It suggests a poor community
understanding of its essence.

Given how ingrained the term is and for how long it has been used, the
problem is probably not a minor one.

d/

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Mon, 15 Sep 2014 14:51:27 -0700

On Mon, Sep 15, 2014 at 1:18 PM, Carsten Bormann <[email-masked]> wrote:

> reference from a future RFC?  I can't think of anything authoritative,
>

I saw that one, but I didn't know if that URI is considered permanent
enough to be used as a citation in an RFC.  Since there's precedent, I
guess that answers my question.  Thanks!

-MSK

---

From: Ira McDonald <[email-masked]>
Date: Mon, 15 Sep 2014 17:57:05 -0400

Hi,

I agree with Dave Crocker's comments.  Citing REST, in the absence of
a concise definition, is dubious in any open standard.

Cheers,
- Ira

On Mon, Sep 15, 2014 at 4:31 PM, Dave Crocker <[email-masked]> wrote:

> > On 15 Sep 2014, at 22:22, Dave Crocker <[email-masked]> wrote:>> A
> "definition" is usually relatively short, measured by a few
> >> sentences.
> >
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: Nico Williams <[email-masked]>
Date: Mon, 15 Sep 2014 17:01:39 -0500

> a concise definition, is dubious in any open standard.

We have some enormous RFCs.  Spec length is not the problem.  The
problem is that a dissertation generally doesn't make a good spec, but
also ISTM that a pithy description of REST (or a very useful subset of
it) should be feasible.

Nico
--

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 16 Sep 2014 00:01:54 +0200

On 15 Sep 2014, at 23:57, Ira McDonald <[email-masked]> wrote:

> Citing REST, in the absence of 

I don’t get it.

Say,

> citing TCP, in the absence of 

wouldn’t work for me, either.
You need to read that RFC, and the others that followed, and the roadmap RFC, and the bis I-D for that roadmap RFC, etc.  (Of course, if we do any reference for TCP at all, we just reference RFC 793 and act like the other ones don’t matter.)

Grüße, Carsten

---

From: Tim Bray <[email-masked]>
Date: Mon, 15 Sep 2014 15:16:13 -0700

On Mon, Sep 15, 2014 at 2:57 PM, Ira McDonald <[email-masked]>
wrote:
​​

> ​​
> ​​

​I agree. Asserting RESTfulness can get you into theological arguments; for
example, people will come after you for insufficient HATEOS-fu.

In practice, out there in the industry, RESTful has come to be effectively
a synonym for “Everything is done with HTTP and routed through
GET/POST/PUT/DELETE.”  I note that the IETF has excellent reference
material to support that kind of assertion in our drafts.

​​

​​

-- 
- Tim Bray (If you’d like to send me a private message, see
https://keybase.io/timbray)

---

From: Ira McDonald <[email-masked]>
Date: Mon, 15 Sep 2014 18:19:01 -0400

Hi Carsten,

Security and computing glossaries do indeed have brief, descriptive
definitions of TCP (coupled w/ an RFC 793 backing reference).

If REST or RESTful cannot be concisely defined and also no RFC or
other public standard extended definition exists, then using the term
in IETF standards-track specs is dubious.

I liked Tim Bray's further comment a moment ago.

Cheers,
- Ira

On Mon, Sep 15, 2014 at 6:01 PM, Carsten Bormann <[email-masked]> wrote:

> You need to read that RFC, and the others that followed, and the roadmap
> RFC, and the bis I-D for that roadmap RFC, etc.  (Of course, if we do any
> reference for TCP at all, we just reference RFC 793 and act like the other
> ones don’t matter.)
>
> Grüße, Carsten
>
>

---

From: mike amundsen <[email-masked]>
Date: Mon, 15 Sep 2014 18:36:22 -0400

>
> yes, since the dissertation is not *about* REST (REST is the example),
> there is no simple definition there.
>
> i suspect something that combines the first para in Fielding's chapter
> 5[0] with the second para in this wiki entry about impressionism[1] would
> proly be useful.
>
> i might take a shot if it's thought useful. would this be a worthwhile
> (tiny) Informational RFC?
>
>
> [0] http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
> [1] http://en.wikipedia.org/wiki/Impressionism
>
>
> On Sep 15, 2014 4:31 PM, "Dave Crocker" <[email-masked]> wrote:
>

---

From: Dave Crocker <[email-masked]>
Date: Mon, 15 Sep 2014 15:36:48 -0700

> You need to read that RFC, and the others that followed, and the roadmap RFC, and the bis I-D for that roadmap RFC, etc.  (Of course, if we do any reference for TCP at all, we just reference RFC 79…

I'm not against including a citation; it's relying on an entire book to
provide a meaningful definition to the reader that is the problem.

Citing TCP is useful as a counter-example, because it permits
highlighting some interesting differences.

The major difference, IMO, is that TCP is a very specific protocol,
whereas REST(ful) is more like a paradigm (or, if it weren't such a
dangerous term in the IETF these days, I'd say "pattern".)

So it is more conceptual and used to describe a protocol "approach".
The more vague the concept, the more important a usefully and concise
definition is needed, if we want different people to use the term with
any sort of common meaning.

It is also true that the essence of TCP can be, and has been, described
very concisely, so that it's pretty to understand what it's about
without reading the spec.[1][

We need the same thing for REST.

d/

[1]   I think the second and third sentence in the Wikipedia entrance is
just dandy:

      "TCP provides reliable, ordered and error-checked delivery of a
stream of octets between programs running on computers connected to a
local area network, intranet or the public Internet. It resides at the
transport layer."

---

From: Karl Dubost <[email-masked]>
Date: Tue, 16 Sep 2014 07:52:38 +0900

Murray, who started this thread, has said he was satisfied: 

Le 16 sept. 2014 à 06:51, Murray S. Kucherawy <[email-masked]> a écrit :
> I saw that one, but I didn't know if that URI is considered permanent enough to be used as a citation in an RFC.  Since there's precedent, I guess that answers my question.  Thanks!

So I guess that solves somehow the purpose of this thread?
Discussing about creating a definition without knowing the context of it doesn't really work either. 

-- 
Karl Dubost 🐄
http://www.la-grange.net/karl/

---

From: Dave Crocker <[email-masked]>
Date: Mon, 15 Sep 2014 15:51:22 -0700

> Discussing about creating a definition without knowing the context of it doesn't really work either.

If the definition of REST(ful) depends upon the context in which the
definition is used.... oh boy...

d/

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Mon, 15 Sep 2014 15:57:56 -0700

> We need the same thing for REST.

I asked this question because there's a document in a WG I'm chairing (not
this one) that I believe needs such a definition, either included or
referenced.  I'm happy to push for such a definition to be included in that
document, but only if one can be found or generated, such that it has
consensus, in fairly short order because we have a timeline to which we're
trying to adhere.

I'm inclined to do what RFC7252 did in the absence of something else,
because it has precedent.  On the flipside, if such a definition could be
generated that's satisfactory to this community, then the document could
include that, and future IETF work could conveniently reference it.

Another option would be to create an RFC including such a definition that
could then be cited by other future work, but that seems like a lot of
process just to write down a definition for something.  At least that would
decouple it from that other WG's strict timeline.

-MSK

---

From: Karl Dubost <[email-masked]>
Date: Tue, 16 Sep 2014 08:05:26 +0900

Le 16 sept. 2014 à 07:51, Dave Crocker <[email-masked]> a écrit :
> definition is used.... oh boy…

* cow: (verb) to intimidate
* cow: (noun) a fully grown female animal of a domesticated breed of ox
* cow: (noun) a domestic bovine animal, regardless of sex or age.
* cow: (noun) include here derogatory meaning
* cow: (culture) symbol used in many religions for representing gods.
* cow: (culture) animal which has been banned for consumptions in some populations.

There are many ways of looking at one word. REST is exactly a good example of that from Roy's thesis to the multiple usage and understanding by different communities. :)

---

From: "Rushforth, Peter" <[email-masked]>
Date: Tue, 16 Sep 2014 14:43:11 +0000

Hi,

Although there are many overloaded words in language, REST has been underloaded, in the sense that the
some of the important qualities that the term was coined to describe and evoke have been discarded by 
common usage.    Perhaps HATEOAS is *the most* important such quality, as it forms the basis of the standard
Web, which currently separates us from platformification or what have you.

RFC authors would benefit from an RFC for REST, IMHO.  At least it could be useful as a stick to beat those organizations which
omit HATEOAS from their definition of REST.   Similar to the utility of RFC 7320.

Regards,
Peter Rushforth

---

From: Mark Baker <[email-masked]>
Date: Tue, 16 Sep 2014 10:49:25 -0400

> An entire book is rather too long to qualify.

It's really only chapter 5 that defines REST, with the preceding
chapters defining terms and concepts that enable chapter 5. If those
terms and concepts were themselves commonly used in IETF circles, I'd
suggest referencing chapter 5 directly, but they aren't so I see no
problem referencing the whole dissertation.

tl;dr RTFM

---

From: Dave Crocker <[email-masked]>
Date: Tue, 16 Sep 2014 07:52:02 -0700

> problem referencing the whole dissertation.

Other than the fact that it's useless?

Citing only an entire volume, as a means of defining a concept, vastly
raises the barrier to utility of the document making the citation.

It also tends to indicate a community failure to develop a shared
understanding of the construct.

d/

---

From: Erik Wilde <[email-masked]>
Date: Tue, 16 Sep 2014 08:01:47 -0700

hello.

having spent considerable time and energy in the REST space, i think it 
would be great if the IETF had some minimal guidance on what it is, why 
it matters, and what people might want to consider when trying to be 
RESTful.

there are two extremes:

- one is to be pure and insist on the fact that REST is not a 
technology, but an architectural style. this is "correct", but most 
people think this is not very helpful.

- tim bray's pragmatic view that anything using HTTP these days is being 
sold as RESTful. this is a bit sad, but this is how it is.

a useful definition would be in between. focusing on actual 
technologies, but still making explicit statements about the things that 
matter for being RESTful.

> Web, which currently separates us from platformification or what have you.

REST really does not define that many constraints, and hypermedia is an 
important one. at least highlighting that (even if people often choose 
to ignore it) might be helpful to some.

in my experience, people that just want to call something "REST" because 
it's hip or sells better will not care about descriptions or guidelines 
anyway. they just want the branding. but there also are many who are a 
bit confused by "The Definition" (it's not a technology, it's an 
architectural style) and the use of the term out in the wild. those 
people might be served very well with a concise document that makes some 
simple statements about what matters most.

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Mark Baker <[email-masked]>
Date: Tue, 16 Sep 2014 11:40:31 -0400

> raises the barrier to utility of the document making the citation.

Presumably these aren't normative references, as that would make no
sense. But an informative reference would seem the perfect vehicle for
the editors to inform readers about some of the decisions made in the
design of the protocol.

> understanding of the construct.

Not at all from my POV. That seems par for the course when one
community wants to be informed by another.

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 16 Sep 2014 18:32:29 +0200

> I asked this question because there's a document in a WG I'm chairing (not this one) that I believe needs such a definition, either included or referenced.  

You mean as in defining/referencing REST in a normative way?
I’d love to know what that document is trying to accomplish.

(The current discussion does not make any sense if the point is just about an informative reference to the concept — clearly the thesis is fine for that, and there are secondary sources such as Wikipedia for those who want to save time.)

> I'm happy to push for such a definition to be included in that document, but only if one can be found or generated, such that it has consensus, in fairly short order because we have a timeline to which we're trying to adhere.

Section 4 of the Wikipedia article is a pretty concise definition of REST (if it is the architectural constraints you are after).  Probably section 2 and 3 are needed, too, for context.  Of course, you could just list the names of the six architectural constraints; this would be even more concise but not really meaningful any more.

But I still question the point here.

When we need a unit for time in IETF standards, we use “seconds”, generally without referencing ISO/IEC 80000.

If we were into cabling standards, we would use terms such as “green” for the color of a strand’s isolation without a formal definition of “green".

Obviously, the term “green” is being abused in the industry about as much as the term “REST" is, but that wouldn’t change the above (it would be obvious from context this is not about “eco-friendly” isolation).

Grüße, Carsten

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Tue, 16 Sep 2014 10:39:16 -0700

> I’d love to know what that document is trying to accomplish.

I mean defining it at all, in the same way that a reviewer running across
an acronym with which she is unfamiliar needs to know what it means to
understand what's going on in the rest of the document.  I'm basically
trying to resolve a "Define this term on first use".

It's hardly uncommon for us to insist on expansion of an acronym on first
use and then also include a definition or a reference to one, is it?

>
> When we need a unit for time in IETF standards, we use “seconds”,
> generally without referencing ISO/IEC 80000.

> If we were into cabling standards, we would use terms such as “green” for
> the color of a strand’s isolation without a formal definition of “green".
>

I hope it's not actually debatable that there are more RFC readers who know
what seconds and green are than who know what REST means.

I get that you think a good understanding of REST is ubiquitous;
respectfully, I disagree (because I didn't until recently, for example),
and I'd like to ensure this document accommodates those readers who don't.

-MSK

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 16 Sep 2014 20:06:53 +0200

> I mean defining it at all, in the same way that a reviewer running across an acronym with which she is unfamiliar needs to know what it means to understand what's going on in the rest of the document.  I'm basically trying to resolve a "Define this term on first use". 
> 
> It's hardly uncommon for us to insist on expansion of an acronym on first use and then also include a definition or a reference to one, is it?

Ah, good, that’s exactly what we needed in RFC 7252, and which has been solved by the reference to the dissertation.
So my recommendation would, again, be to mirror that (or the reference in RFC 7231).

> I hope it's not actually debatable that there are more RFC readers who know what seconds and green are than who know what REST means.

To the level of a formal definition?  E.g., based on the CIE 1931 color model or L*a*b* coordinates?  I’m not so sure...
For some reason some people seem to insist on a formality of the definition of what REST is that we wouldn’t require in other places.  May have something to do with the marketing value of the term and the desire for “requirements engineering”*)...

> I get that you think a good understanding of REST is ubiquitous;

Ubiquitous: certainly not (outside the small circle that really cares about Web architecture, that is).
Readily achievable: I wish that there were a good, authoritative, reasonably correct tutorial document that one could cite, but for now, the dissertation (or, for a more superficial understanding, some secondary literature like the Wikipedia article) will have to do.

I just don’t think that “a good understanding of REST” can be conveyed by a concise definition.
So, if that is what is actually needed, the reference to the dissertation is even more necessary.

Grüße, Carsten

*) “requirements engineering”, in standardization, is the engineering of the requirements in such a way that only your preferred solution meets the requirements.  A common way of generating the necessary “consensus” for those is to employ terms that sound good but have a formal meaning with some non-obvious consequences.

---

From: Tim Bray <[email-masked]>
Date: Tue, 16 Sep 2014 11:20:48 -0700

Seriously, I would actually ask whether your need is to appeal to the full
intellectual apparatus of REST, or simply to say “We’re using 4-verb HTTP
and respecting the idempotence semantics”.  Because in a huge proportion of
case, the latter is what people really mean.  And there’s nothing wrong
with that.

On Tue, Sep 16, 2014 at 10:39 AM, Murray S. Kucherawy <[email-masked]>
wrote:

> I hope it's not actually debatable that there are more RFC readers who
> know what seconds and green are than who know what REST means.
>

---

From: Hector Santos <[email-masked]>
Date: Tue, 16 Sep 2014 16:09:42 -0400

Murray,

Historically, when it came to RPC (Remote Procedure Calls) API 
development that included web servers, client/servers, etc, the key 
was how was the API defined (the options) and the data passed.

In general, you can do GET and/or POST.  But most servers did not do 
both.  Either one or the other.

POST was harder to do and migrate too, but it allowed for the 
"unlimited" or larger data part needs. SOAP is a good example of this 
API.  A SOAP API can be RESTFUL as well if you are passing options via 
the command line.

Overall, the shortest definition that MOST should understand is:

       WEB-based Application Command line (URL) options.

You can't do that with POST.  Its only GET.

I remember when the term REST began to be used when many systems 
direction were developing APIs and using URL COMMAND LINE Options for 
their system or operation was the simplest and quickest path. Doing a 
SOAP was "harder."

So to me, when you say "REST" or "RESTFUL" I am expecting GET command 
line options.

Note: Some servers can take a POST and present the data to the 
server-side applications as GET values.  The server side application 
is independent of how the data/options are passed (Command Line versus 
Posted).

I suggest to just look at the RFC HTTP documents for the following 
definitions:

     request line
     request query
     query

I think a reference to the HTTP RFCs regarding "HTTP GET query 
command" or anything close to that is probably the best "layman" 
definition for REST.

--
HLS

-- 
HLS

---

From: Erik Wilde <[email-masked]>
Date: Tue, 16 Sep 2014 17:33:25 -0700

hello carsten.

> So, if that is what is actually needed, the reference to the dissertation is even more necessary.

agreed that definitions usually not good tutorial materials. But a 
concise definition does not exclude a reference to more exhaustive 
documentation, right? we've had at least some success with presenting 
people with an easy "check list", telling them that if you miss any of 
those, you probably have an issue with actually doing REST:

"What is REST? A set of constraints that inform an architecture
  * Resource Identification
  * Uniform Interface
  * Self-Describing Messages
  * Hypermedia Driving Application State
  * Stateless Interactions"

http://dret.net/netdret/docs/rest-icwe2010/rest#%2812%29

but then again, that's against tim bray's more pragmatic view of 
"anything that's using HTTP and some reasonable set of methods without 
violating their HTTP semantics".

cheers,

dret.

---

From: mike amundsen <[email-masked]>
Date: Tue, 16 Sep 2014 20:48:16 -0400

*style* definitions don't need to be "pragmatic", they need to be
helpful/useful/etc. in a disputed space (e.g. the arts) definitions can be
identified by "schools", etc.

*implementation* advice can be pragmatic or pedantic or anything in between.

whether style or implementation, the definitions should be useful/helpful.

mamund
+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

On Tue, Sep 16, 2014 at 8:33 PM, Erik Wilde <[email-masked]> wrote:

> agreed that definitions usually not good tutorial materials. But a concise
> definition does not exclude a reference to more exhaustive documentation,
> right? we've had at least some success with presenting people with an easy
> "check list", telling them that if you miss any of those, you probably have
> an issue with actually doing REST:
>
> but then again, that's against tim bray's more pragmatic view of "anything
> that's using HTTP and some reasonable set of methods without violating
> their HTTP semantics".
>
> cheers,
>
> dret.
>
> --

---

From: Dave Cridland <[email-masked]>
Date: Wed, 17 Sep 2014 04:14:55 +0100

> understanding of its essence.
I think you're misunderstanding. "REST" is not a technical term, but a
religious one.

> problem is probably not a minor one.
Right. Consider:

"To some extent, people get REST wrong because I failed to include enough
detail on media type design within my dissertation. That’s because I ran
out of time, not because I thought it was any less important than the other
aspects of REST. Likewise, I suspect a lot of people get it wrong because
they read only the Wikipedia entry on the subject, which is not based on
authoritative sources." (Roy Fielding, 2008).

What he's saying here is that:

a) The thesis is incomplete.
b) Any other document is not "authoritative".

The net result is that there exists no description of REST, and therefore
nothing to cite.

Dave.

---

From: Andrew Newton <[email-masked]>
Date: Wed, 17 Sep 2014 12:20:45 -0400

On Tue, Sep 16, 2014 at 2:20 PM, Tim Bray <[email-masked]> wrote:
> case, the latter is what people really mean.  And there’s nothing wrong with
> that.

+1

Additionally, I have found that many people use the term "RESTful" to
mean this practical thing they are trying to do and not the whole REST
"religion".

-andy

---

From: Jim Fenton <[email-masked]>
Date: Wed, 17 Sep 2014 10:26:44 -0700

> know what seconds and green are than who know what REST means.

Count me in that group. I avoid using the term REST because I don't know
what's included: is the use of GET/POST/PUT/DELETE verbs sufficient (as
Tim Bray suggests)? Do I also need to include some flavor of .well-known
service discovery? Is there anything special about the way that URIs
need to be structured?

> respectfully, I disagree (because I didn't until recently, for
> example), and I'd like to ensure this document accommodates those
> readers who don't.
>
+1

-Jim

---

From: Dave Crocker <[email-masked]>
Date: Wed, 17 Sep 2014 10:48:07 -0700

>> example), and I'd like to ensure this document accommodates those

The IETF has been showing a pattern of willingness to invoke language
that has tends to have little shared meaning.

What is ironic is that we are in the business of creating specifications
that are precise enough to permit interoperability, yet we are not
inclined to do the same with the vocabulary we use.

One piece of this problem seems to stem from a failure to distinguish
between those already deeply immersed in the topic (and its vocabulary),
versus the rest of the Internet community -- those other folk who will
read the new document and use the new term -- that is not immersed, and
that therefore needs concise and tutorial support material.

Telling such folk that the 'meaning' of a term requires reading an
entire tome is merely a way of preventing informed participation by them.

d/

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 19 Sep 2014 11:37:20 -0700

Hey Murray,

On 15 Sep 2014, at 3:57 pm, Murray S. Kucherawy <[email-masked]> wrote:

> I asked this question because there's a document in a WG I'm chairing (not this one) that I believe needs such a definition, either included or referenced.  I'm happy to push for such a definition to be included in that document, but only if one can be found or generated, such that it has consensus, in fairly short order because we have a timeline to which we're trying to adhere.

I think the important question here is why the WG thinks it needs a reference.

If it’s just a non-normative link to more information about the design choices made in a protocol, referencing Roy’s thesis is entirely appropriate (although I wonder if ti’s necessary; the IETF isn’t publishing academic papers…).

If it’s trying to assert that a protocol has particular properties, or conforms to a particular worldview, it may be more trouble than it’s worth, since (as we’ve seen), the term REST means many things to different people.

I can think of several things that are better to do than this with the IETF’s time. Normally I wouldn’t mind in selected participants having their time consumed by such an effort, but if the output were to try to “define” REST normatively, I suspect that it would end up consuming a lot of my time (and Roy’s, and others’), and so I would object to starting this work.

Cheers,

--
Mark Nottingham   http://www.mnot.net/

---

From: mike amundsen <[email-masked]>
Date: Fri, 19 Sep 2014 14:45:24 -0400

<snip>
if the output were to try to “define” REST normatively, I suspect that it
would end up consuming a lot of my time (and Roy’s, and others’), and so I
would object to starting this work.
</snip>

would you feed differently if this was about creating a reference for an
informative definition?

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Sep 19, 2014 at 2:37 PM, Mark Nottingham <[email-masked]> wrote:

> > I asked this question because there's a document in a WG I'm chairing
> (not this one) that I believe needs such a definition, either included or
> If it’s just a non-normative link to more information about the design
> choices made in a protocol, referencing Roy’s thesis is entirely
> appropriate (although I wonder if ti’s necessary; the IETF isn’t publishing
> academic papers…).
>
> If it’s trying to assert that a protocol has particular properties, or
> conforms to a particular worldview, it may be more trouble than it’s worth,
> since (as we’ve seen), the term REST means many things to different people.
>
> I can think of several things that are better to do than this with the
> IETF’s time. Normally I wouldn’t mind in selected participants having their
> time consumed by such an effort, but if the output were to try to “define”
> REST normatively, I suspect that it would end up consuming a lot of my time
> (and Roy’s, and others’), and so I would object to starting this work.
>
> Cheers,
>
> --

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 19 Sep 2014 11:48:56 -0700

Not really. I see many potential downsides, not a lot of upside.

Now, if someone wanted to go off and write such a document optimistically, and was willing to bring it here to have arrows thrown at it, it could be interesting. It’s just that all of the people who are most qualified to write such a thing are really busy.

YMMV, of course.

Cheers,

On 19 Sep 2014, at 11:45 am, mike amundsen <[email-masked]> wrote:

> <snip>
> if the output were to try to “define” REST normatively, I suspect that it would end up consuming a lot of my time (and Roy’s, and others’), and so I would object to starting this work.
> </snip>
> 
> would you feed differently if this was about creating a reference for an informative definition?
> 
> 
> 
> 
> mamund
> +1.859.757.1449
> skype: mca.amundsen

---

From: Larry Masinter <[email-masked]>
Date: Fri, 19 Sep 2014 21:47:13 +0000

"Defining" the term doesn't seem useful. But what about a BCP  Best Current Practice

"Guidelines for creating RESTful services Protocols"

with a focus on summarizing what future IETF application protocol designers SHOULD do to be RESTful, and when they SHOULD do it.

BCPs carry some weight but allow for exceptions and evolution. If REST isn't a 'best current practice' we should stop talking about it. If it is, then a summary of why and when seems just right for BCP.

> From: apps-discuss [mailto:[email-masked]] On Behalf Of Erik
> Wilde
> Sent: Tuesday, September 16, 2014 8:02 AM
> To: Rushforth, Peter; IETF Apps Discuss
> having spent considerable time and energy in the REST space, i think it would be
> great if the IETF had some minimal guidance on what it is, why it matters, and
> what people might want to consider when trying to be RESTful.
> 
> there are two extremes:
> 
> - one is to be pure and insist on the fact that REST is not a technology, but an
> architectural style. this is "correct", but most people think this is not very
> helpful.
> 
> - tim bray's pragmatic view that anything using HTTP these days is being sold as
> RESTful. this is a bit sad, but this is how it is.
> 
> a useful definition would be in between. focusing on actual technologies, but
> still making explicit statements about the things that matter for being RESTful.
> 
> > Although there are many overloaded words in language, REST has been
> > underloaded, in the sense that the some of the important qualities that the
> term was coined to describe and evoke have been discarded by
> important one. at least highlighting that (even if people often choose to ignore
> it) might be helpful to some.
> 
> in my experience, people that just want to call something "REST" because it's
> hip or sells better will not care about descriptions or guidelines anyway. they
> just want the branding. but there also are many who are a bit confused by "The
> Definition" (it's not a technology, it's an architectural style) and the use of the
> term out in the wild. those people might be served very well with a concise
> document that makes some simple statements about what matters most.
> 
> cheers,
> 
> dret.
> 
> --

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Fri, 19 Sep 2014 14:48:29 -0700

On Fri, Sep 19, 2014 at 11:48 AM, Mark Nottingham <[email-masked]> wrote:

> Now, if someone wanted to go off and write such a document optimistically,
> and was willing to bring it here to have arrows thrown at it, it could be
> interesting. It’s just that all of the people who are most qualified to
> write such a thing are really busy.
>
> YMMV, of course.
>

My goal here is pretty simple: We don't like undefined acronyms in RFCs.
"Please expand HTTP on first use" has to be something you've seen before in
your various document reviews, for example.

How do I resolve that when the acronym is REST?

-MSK

---

From: Erik Wilde <[email-masked]>
Date: Fri, 19 Sep 2014 14:53:04 -0700

hello.

> "Defining" the term doesn't seem useful. But what about a BCP  Best Current Practice

there's a fine line between defining and describing, in particular when 
the authoritative definition itself is on an abstraction level that for 
most practical purposes is one level too high.

> "Guidelines for creating RESTful services Protocols"

i like that. summarize patterns and best practices, and leave it at 
that. that's what in my experience a lot of people already find helpful, 
and when it's just on the "you might want to consider doing it like 
this" level, it's less judgmental than a description/definition.

> with a focus on summarizing what future IETF application protocol designers SHOULD do to be RESTful, and when they SHOULD do it.

... and why it's a good idea and where it's already used successfully in 
some existing and deployed solutions.

cheers,

dret.

---

From: Tim Bray <[email-masked]>
Date: Fri, 19 Sep 2014 15:14:01 -0700

Murray, the question has been raised a couple of times; apologies if you
addressed it and I missed it.  What is the context?  Are you sure you
really mean Representational State Transfer?  Are you sure you couldn’t
just get away by saying something like

“The interface is via HTTP, using the A, B, and C verbs, taking advantage
of the idempotence characteristics of A and C, with the payload being
delivered as application/D, and with a cleanly-designed URI space”

Because there’s nothing in there that you can’t find an good reference for
around here.

On Fri, Sep 19, 2014 at 2:48 PM, Murray S. Kucherawy <[email-masked]>
wrote:

>> Now, if someone wanted to go off and write such a document
>> optimistically, and was willing to bring it here to have arrows thrown at
>> it, it could be interesting. It’s just that all of the people who are most
>> qualified to write such a thing are really busy.
>>
>> YMMV, of course.
>>
>

---

From: mike amundsen <[email-masked]>
Date: Fri, 19 Sep 2014 18:24:02 -0400

yep - BCP seems right to me, too.

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Sep 19, 2014 at 5:47 PM, Larry Masinter <[email-masked]> wrote:

> with a focus on summarizing what future IETF application protocol
> designers SHOULD do to be RESTful, and when they SHOULD do it.
>
> BCPs carry some weight but allow for exceptions and evolution. If REST
> isn't a 'best current practice' we should stop talking about it. If it is,
> then a summary of why and when seems just right for BCP.
>
> would be
> technology, but an
> sold as
> technologies, but
> > > common usage.    Perhaps HATEOAS is *the most* important such quality,
> as
> > it forms the basis of the standard
> it's

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Fri, 19 Sep 2014 16:54:10 -0700

On Fri, Sep 19, 2014 at 3:14 PM, Tim Bray <[email-masked]> wrote:

> addressed it and I missed it.  What is the context?
>

It is, quite literally, a "this acronym should be expanded on first use in
this document" issue, which is a common thing pointed out during AD or IESG
evaluation of a document.

What I think what you mean by "context" is actually more a question about
whether REST is even the right or necessary term to use in this document in
the first place.  That, I think, is a different question than what I'm
trying to answer, although it might even be the more important one.

Still, let me see if I can construct a more concrete example:

"This document describes the use of the HyperText Transport Protocol (HTTP;
[RFC7230]) to provide service X."

So, if I have this, which follows the same common form we use in RFCs:

"This document describes a service that provides service X while adhering
to the principles of REpresentational State Transfer (REST; [xxxx])."

What would you suggest we put for "xxxx" there?

Are you sure you really mean Representational State Transfer?  Are you sure
> you couldn’t just get away by saying something like
>

And that might be absolutely fine.   I'll forward this suggestion to the
authors and let them decide if that solves the reference problem without
losing anything they feel needs to be there.

Thanks!

-MSK

---

From: Nico Williams <[email-masked]>
Date: Fri, 19 Sep 2014 19:27:50 -0500

If "RESTful" and "REST" are merely social signifiers ^W^W informative,
then don't use them in RFCs.  We could also just accept them as
social/cultural signifiers and use them in RFCs without offering a
definition.

OTOH, if "RESTful" and "REST" denote normative semantics, then we must
define them.

Quite aside from that, there have been many arguments about what is
and isn't RESTful (is this an understatement?)...  It'd be nice to
have a clear definition that all accept.  If nothing else I could make
a killing in popcorn stocks if we take up that challenge!

More seriously: I propose that we avoid these terms in Internet RFCs
as much as possible.

Nico
--

---

From: mike amundsen <[email-masked]>
Date: Fri, 19 Sep 2014 21:09:28 -0400

If the word/acronym "REST" is to be used at all in RFCs, it should be
clearly defined (the *word*). Without a useful shared definition of the
word, leaving it out of RFCs is the right thing to do.

FWIW, I think MSK's example is spot on.
<snip>
"This document describes a service that provides service X while adhering
to the principles of REpresentational State Transfer (REST; [xxxx])."
</snip>
Right now, we do not have a proper document for reference. To date, uses of
that word in RFCs have been tied to Fielding's dissertation which is NOT
about REST at all. Referring to the single Chapter that outlines REST is,
IMO, not acceptable since the chapter is full of references to previous
content in the dissertation. I agree w/ Crocker that this is too big a
chunk to use as a reference *for that term*.

A short BCP (per Masinter's suggestion) should suffice.

What I find instructive is that no one here wants to even *hazard* a
definition or point to one (save MSK's reference to the Wikipedia entry).
So I've started an experiment[1] to collect definitions and I invite folks
on this list to offer theirs up (or point to an existing one). I plan use
this material in a short session at RESTFest next week and post
notes/comments from that session.  It would help the convo quite a bit to
see more volunteers adding to the list.

Cheers

[1] https://github.com/RESTFest/2014-Greenville/wiki/Mike-Amundsen#rest

mamund
+1.859.757.1449
skype: mca.amundsen

---

From: "John Levine" <[email-masked]>
Date: 20 Sep 2014 06:22:38 -0000

In article <[email-masked]> you write:
>optimistically, and was willing to bring it here to have arrows thrown
>at it, it could be interesting. It’s just that all of the people who are
>most qualified to write such a thing are really busy.

This sounds completely correct to me.  I look forward to seeing what
the people who think that such documents would be useful write.

R's,
John

---

From: Matthew Kerwin <[email-masked]>
Date: Sat, 20 Sep 2014 18:09:35 +1000

> What would you suggest we put for "xxxx" there?
​Seems to me to be a perfectly reasonable situation to reference Roy's
dissertation. "Adhering to principles" is already pretty hand-wavey, so I
think the reference doesn't have to be particularly formal.  Adhering to
the principles of Buddhism doesn't require a reference to a BCP of the Five
Precepts.

Alternatively, as Tim says, you could replace the reference with an inline
enumeration of the principles, if that doesn't introduce Too Much Words.

-- 
  Matthew Kerwin
  http://matthew.kerwin.net.au/

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 20 Sep 2014 10:20:31 +0200

> How do I resolve that when the acronym is REST?

I thought I gave a recipe already:

   bla bla bla Representational State Transfer [REST] bla bla bla

No consensus definition of the term needed.

(People can find secondary literature about REST in Wikipedia, in bookstores, and in a few blogs.
There is no need to reference all that secondary literature.
And we stopped publishing FYIs a while ago.)

More importantly, I’ll repeat myself:

If somebody thinks they need a normative definition of REST in their protocol specification, I’d really like to know  what that is trying to achieve.

I like Mike’s experiment, but I agree with Mark that the IETF has no need to spend an enormous amount of cycles on this.

I’m having a little de ja vu here with respect to the US “debate” about evolution:
There is a published opinion that likes to make it look like there is a great debate about what REST means.
Frankly, I’m not aware of such a debate.
(There *is* a debate whether it is always the right thing to follow all constraints of REST.
The term RESTful was invented to indicate a varying degree of adherence to them; it does not have a well-defined meaning except just that, so debating whether something “is RESTful” degenerates into a discussion of taste.
There also have been debates around fine points of REST practice, say, the meaning of POST.
Finally, REST practice is evolving, e.g. via the PATCH method (RFC 5789) and URI templates (RFC 6570), but the basic constraints are surprisingly stable.)

Grüße, Carsten

---

From: Hector Santos <[email-masked]>
Date: Sat, 20 Sep 2014 10:58:38 -0400

> How do I resolve that when the acronym is REST?

It depends in how you will be using it.  Maybe you don't have a "REST" 
situation? and just a normal concept of preparing a HTTP query?  Thats 
pretty standard and plenty of HTTP RFC references for that.

Are you really developing a REST API?  If so, then I guess you want to 
use Roy's document but you SHOULD also reference the HTTP RFC docs as 
that is the basic even for Roy's doc.

We write APIs Murray and we have very rich set of API for nearly all 
the native languages, including "REST" forms of the API for the WEB 
side interfaces.  I am not going to read Roy's doc unless there is 
something very specific you want us to know about thats only found 
there and not in an standard HTTP docs.

Maybe for your specific Protocol, you don't need to mention REST at 
all unless you think it will help with your "technical marketing" of 
the protocol.

If you want to cater to the "layman" application developer and 
implementer as you stated you desired to, you can say....

    Protocol XYZ is a "REST" based protocol. REST which stands for
    "Representational State Transfer" [REST] is a common industry
    term  used for preparing HTTP Queries [HTTP] for Web-based API
    development.

    [REST] Representational State Transfer
           http://en.wikipedia.org/wiki/REST_API

    [HTTP] Hypertext Transfer Protocol -- HTTP/1.1
           http://tools.ietf.org/html/rfc2616

Keep it simple.

-- 
HLS

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Sat, 20 Sep 2014 08:01:06 -0700

> I thought I gave a recipe already:

Yes, you did, but I was asked again why this is needed, so I answered.

More importantly, I’ll repeat myself:
>
> If somebody thinks they need a normative definition of REST in their
> protocol specification, I’d really like to know  what that is trying to
> achieve.
>

> "This document describes a service that provides service X while adhering
to the principles of REpresentational State Transfer
> (REST; [xxxx])."

What I'm trying to achieve is an answer to that question for a document I'm
shepherding.  You've given one answer (more than once now); thank you for
that.  Other people seem to have other opinions, in some cases suggesting
the document should be saying something else completely.  That's why this
thread is still going.

I like Mike’s experiment, but I agree with Mark that the IETF has no need
> to spend an enormous amount of cycles on this.
>

I agree.  I just want to move this document forward.

-MSK

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 20 Sep 2014 18:01:35 +0200

On 20 Sep 2014, at 17:01, Murray S. Kucherawy <[email-masked]> wrote:

> for a document I'm shepherding

It’s probably easier to answer your question in an intelligent way if you share what that document is...

As posed, this simply is not a new question, and there is the tried and true answer [RFC 6120, RFC 6503, RFC 6690, RFC 7231, RFC 7252], variations of which Julian and I gave.  RFC 6392 chose not to give a reference, and this and other documents [RFC 7285] use the term “RESTful” or “REST-ful” without distinction from REST, RFC 6272 even seems to equate it with REST.  (A few more documents, e.g. RFC 6574, are using “RESTful” as a part of the name of the CoRE working group only.  By now you probably can guess why I do care about this issue.)

Grüße, Carsten

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Sat, 20 Sep 2014 22:51:08 -0700

> share what that document is...

Have a look at
https://datatracker.ietf.org/doc/draft-ietf-weirds-using-http/.

-MSK

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 21 Sep 2014 09:34:54 +0200

On 21 Sep 2014, at 07:51, Murray S. Kucherawy <[email-masked]> wrote:

> Have a look at https://datatracker.ietf.org/doc/draft-ietf-weirds-using-http/.

Thanks.  To avoid the somewhat ill-defined “RESTful”, I would change “RESTful practices” into “practices informed by the Representational State Transfer [REST] architectural style”, change “RESTful web services” similarly into “web services informed by the Representational State Transfer [REST] architectural style", and add the reference.

Grüße, Carsten

---

From: Hector Santos <[email-masked]>
Date: Sun, 21 Sep 2014 12:23:11 -0400

On 9/21/2014 3:34 AM, Carsten Bormann wrote:
> Thanks.  To avoid the somewhat ill-defined �RESTful�, I would change �RESTful practices� into �practices informed by the Representational State Transfer [REST] architectural style�, change �RESTful web services� similarly into �web services informed by the Representational State Transfer [REST] architectural style", and add the reference.
>
> Gr��e, Carsten

That or remove it all together and just say "standard web-based (or 
http) query methods.  In fact, at the end of the intro, it says this:

    The purpose of this document is to clarify the use of standard HTTP
    mechanisms for this application.

That line should probably in the abstract and/or earlier in the intro.

RESTFul should only suggest to the reader that there is a formal 
HTTP-query-based API for input and output.  I haven't read Roy's doc 
but I don't think I need to. Does the reader need to read it?

Anyway, thats my opinion. "RESTFUL practices" is fine to me because I 
am an API developer so I know what it means or what it tries to imply.

Question, does Roy's doc provide a mechanism or methods for optimizing 
HTTP Client/Service query frameworks?  If it does, then the reader 
might be interesting in exploring that if that is what "Restful 
Practices" means.

-- 
HLS

---

From: Tim Bray <[email-masked]>
Date: Sun, 21 Sep 2014 09:54:15 -0700

On Sun, Sep 21, 2014 at 9:23 AM, Hector Santos <[email-masked]> wrote:

Anyway, thats my opinion. "RESTFUL practices" is fine to me because I am an
> API developer so I know what it means or what it tries to imply.
>

​In industrial practice it means JSON-over-HTTP.

In this document, I think it amounts to arm-waving. I think the best
solution to Murray’s problem in this case is is to remove the ​term
RESTful; I don’t think it really adds value to the draft.

> HTTP Client/Service query frameworks?  If it does, then the reader might be
> interesting in exploring that if that is what "Restful Practices" means.
>
> --
> HLS
>
>
>

---

From: Mark Baker <[email-masked]>
Date: Tue, 23 Sep 2014 13:24:15 -0400

On Sun, Sep 21, 2014 at 1:51 AM, Murray S. Kucherawy
<[email-masked]> wrote:
> Have a look at
> https://datatracker.ietf.org/doc/draft-ietf-weirds-using-http/

While that draft is far better than the bulk of HTTP-using drafts I've
seen over the years, I see no value in the mention of REST/RESTful. It
doesn't even appear to be using hypermedia, as IIUC, the client is
responsible for constructing URIs without explicit license from the
server.