RE: Hypermedia vs. data (long)

Well said Chris.  This should be linked to as a canonical posting on the
topic.

IMO, the gajillions of XML vocabularies that people are going to design and
interchange are what make the need for web services.  As Simon Phipps says,
"Web Services is simply XML in motion".  We have to figure out how programs
understand that XML in motion.

Cheers,
Dave
  -----Original Message-----
  From: www-ws-arch-request@w3.org [mailto:www-ws-arch-request@w3.org]On
Behalf Of Christopher B Ferris
  Sent: Tuesday, December 31, 2002 9:24 AM
  To: Mark Baker
  Cc: www-ws-arch@w3.org
  Subject: Re: Hypermedia vs. data (long)



  Mark,

  Understood. However, the use of URIs to link things is not the part of
hypermedia
  that is troublesome. That's the "hyper" part, which is indeed critical and
desirable. Rather, it is the "media"
  part that has many of us troubled. It is the fact that most hypermedia on
the Web today is HTML
  which user agents (typically browsers) "understand". The primary function
of the user agents in the system
  is to render the representation retrieved from a URI on to the user's
screen. The user agents know which
  elements are links because they "understand" the markup language of the
retrieved
  representation (usually HTML). If the representation received is
text/plain, then the user agent
  can employ some pattern matching to identify any potential URIs, but
that's about as sophisticated
  as it gets.

  The HUMAN at the keyboard is the agent that brings all of the
"understanding"
  of the information rendered before them on the computer screen. Sure,
there are spiders,
  bots, and crawlers whose sole purpose is to traverse/harvest the links.
But again, they
  need only have a limited set of media types to understand, they can ignore
the
  ones that they don't (for the most part) and they are rarely charged with
"understanding"
  the content beyond finding more links to traverse.

  Thus, user agents on the Web have little need of any *description* of what
is at the
  other end of a link, because it is "assumed" to be either text/* (which it
is free to render
  as text/plain if it doesn't understand the media type received), image/*
which it can
  ignore if it chooses, or application/* which it is also free to ignore.
All it needs to do is
  render the received/retrieved representation and the human does the dirty
work
  of making sense of what has been rendered.

  The user agent is not concerned with whether the text/html representation
of http://example.org/foo.html
  is a representation of a resource about human anatomy, politics, a
purchase order, or a description
  of my car. All it needs to "understand" is text/html (well, technically,
all it *really* needs to understand
  is text/* since it can simply display/render the received HTML document as
plain text and
  let the human do the understanding of the HTML tags and the content that
they markup). Thus,
  the programmers who develop the user agents for the Web need only to read
the HTML
  spec(s) to develop an effective user agent. That is all the description
that they need. The function
  of the developed user agents is not to understand the content beyond the
presentation markup
  of the HTML vocabulary.

  With Web services, we are trying to enable interaction of fairly
autonomous resources/agents on the Web.
  The agents in the system must be prepared to "understand" the
representations of the resources
  they receive. They have need of understanding not only the
application/soap+xml media type
  (for many Web services, this will be the media type exchanged), but they
also need to "understand"
  the schema of the contents of the SOAP Header and Body elements, as these
are not defined
  by the SOAP specification. The SOAP specification defines only the
processing model, not the
  contents. Whether or not the contents of the SOAP Header or Body contain
references (links)
  to other resources is irrelevant to the discussion, IMO.

  Let's examine a use case using HTML and see where it leads us.

  Suppose I have a Web resource such as your lightbulb example. It returns a
representation of
  itself as an HTML document. e.g.

  <html>
  <head>
    <title>a lightbulb</title>
  </head>
  <body>
    <p>I am a lightbulb. I am on.</p>
    <form action="http://example.org/light" method="POST">
      <input type="hidden" name="state" value="off"/>
      <input type="submit">Turn me off</input>
    </form>
  </body>
  </html>

  Which returns:

  <html>
  <head>
    <title>a lightbulb</title>
  </head>
  <body>
    <p>I am a lightbulb. I am off.</p>
    <form action="http://example.org/light" method="POST">
      <input type="hidden" name="state" value="on"/>
      <input type="submit">Turn me on</input>
    </form>
  </body>
  </html>

  All very RESTful:)

  This is an effective means of achieving an implementation of the
lightbulb. However, unless the
  user agent is endowed with a) an understanding that the URI
http://example.org/light happens to
  be a resource that is (or identifies) a lightbulb, or b) can understand
english and infer that it is a lightbulb
  by parsing and groking the contents of the <p> tag. Also, while it may
seem obvious to a human
  that pressing the "Turn me off" button in the form will effectively toggle
the state of the lightbulb to
  "off", a software agent would need to either a) understand english and
infer that were the case
  or b) have been programmed to "know" that the representation of
http://example.org/light contains
  a FORM that when submitted, will toggle the state of the identified
lightbulb.

  Let's extend the example a bit further. Let us assume that this lightbulb
happens to be connected
  to a dimmer switch. Thus, we might have:

  <html>
  <head>
    <title>a lightbulb</title>
  </head>
  <body>
    <p>I am a lightbulb. I am at 25% brightness.</p>
    <form action="http://example.org/light" method="POST">
      Choose a brightness level:<br/>
      <input type="radio" name="state" value="0">Off</input>
      <input type="radio" name="state" value="25" checked="true">25%</input>
      <input type="radio" name="state" value="50"/>50%</input>
      <input type="radio" name="state" value="75"/>75%</input>
      <input type="radio" name="state" value="100"/>100%</input>
      <input type="submit">Make me glow, or not, as suits your
fancy.</input>
    </form>
  </body>
  </html>

  Oops! Now we require some intellegence to make this work. The user agent
must choose from
  a set of options. Hence, it must understand the relationship between the
options at the resultant
  state that they will leave the light in following submission of the form.
A human would have little
  trouble making sense of this even if they had not had any a priori
knowledge of the representation
  of the lightbulb. Heck, you could replace the toggle on/off switch with a
dimmer switch and the
  human would not be phased in the least. This is, I am sure you would
agree, the beauty of REST.
  The user agents need to be changed relatively infrequently, to endow them
with capabilities to
  render new media types as they are (infrequently) developed. The human
provides the adaptive
  software (it's called a brain) that provides the
intellegence/understanding to this system.

  However, a software agent would be confounded until the developer got
around to programming
  in the new software.

  So, for Web services to function effectively, we need some means of
*describing* a resource
  that is a Web service. The description gives the developer of a
prospective Web service consumer
  the information that they require to develop the software that will
"understand" the message(s) that
  they send/receive to/from the Web service provider. The "understanding"
for Web services is
  imbued at design time by the developer(s) of the software agents at the
two endpoints, using the
  description of the Web service, into the software that aguments the SOAP
processor (in many cases).
  These agents will have a limited, or shall I say focused, "understanding",
and hence can only
  communicate with other agents that share the same description.

  It is my belief that what you are hearing from many of us is that REST
lacks a formal description
  capability because it assumes mostly that the user agents will be charged
with "understanding"
  but a few select media types and that "understanding" is limited to
rendering the representation,
  typically for consumption by a human. I do not believe that you are
hearing us say "Links? We doan need no
  steenkin' links":)

  Quoting again from Roy's thesis, section 5.2.1 Data elements:

  "A distributed hypermedia architect has only three fundamental options: 1)
render the data where it is located and send a fixed-format image to the
recipient; 2) encapsulate the data with a rendering engine and send both to
the recipient; or, 3) send the raw data to the recipient along with metadata
that describes the data type, so that the recipient can choose their own
rendering engine."

  Render, rendering engine, rendering engine... In the previous paragraph,
same section:

  "When a link is selected, information needs to be moved from the location
where it is stored to the location where it will be used by, in most cases,
a human reader. "

  [Appologies in advance if the emphasis in the quote above is lost as it
was the last time I tried to add emphasis using
  markup.]

  Further on in the same section:

  "REST components communicate by transferring a representation of a
resource in a format matching one of an evolving set of standard data types,
selected dynamically based on the capabilities or desires of the recipient
and the nature of the resource."

  I believe that this statement is refering to the (limited) set of standard
media types, most notably HTML. Again, the function/purpose of
  the user agent in this system is to render the representation so that a
human can make some sense of things. Because a human can
  reason, there is no need in REST of the descriptive aspect to specify the
nature of the messages that are exchanged. This is implied in REST
  by having a limited set of standard media types for browsers to render.
They are described by means of their specification, and they all
  share a common processing from the perspective of the user agent:
rendering.

  Of course, it would be great if the world could settle on standards for
things such as Purchase Orders, Invoices, etc. etc.
  That will definitely be a key to the success of Web services in the long
run. However, that will take considerable time
  to evolve. We still have a need to expose existing software which is
typically not standards-based using technology that
  is independent of the underlying platform and language. Enterprises are
(rightly so) reluctant to simply replace all of
  their deployed software with something new, but they do want to be able to
expose what they have using technology
  such as is being provided through Web services to extend the reach and
value of their deployed software.

  So, this is where we are today. There is NOTHING in Web services that
precludes use of hyperlinks in a manner that
  you describe. There is NOTHING in Web services that precludes use of a
standardized interface. That too will take
  time. You keep asserting that just because REST has the generic methods of
GET, PUT, POST, DELETE that that is
  what allows it to scale. I would think that this is partly true, but
again, it has only been demonstrated to work when there is
  an assumption that the agent doing the GET has but a single
responsibility, that of rendering the received representation
  so that a human can apply reasoning to make sense of what to DO with the
received representation, or what effect
  might ensue should a PUT, POST or DELETE on the resource be invoked, based
on unstructured information carried
  between the presentation markup.

  Cheers,

  Christopher Ferris
  Architect, Emerging e-business Industry Architecture
  email: chrisfer@us.ibm.com
  phone: +1 508 234 3624


        Mark Baker <distobj@acm.org>
        Sent by: www-ws-arch-request@w3.org
        12/30/2002 09:38 PM
       To www-ws-arch@w3.org
              cc
              Subject Hypermedia vs. data








  Greetings,

  I recall some discussions with Eric, and perhaps others, in which
  claims roughly equivalent to "REST is good if you have hypermedia, and
  not if you don't" were made, to which I tried to explain that hypermedia
  was a form of solution, not a precondition.

  While responding to a recent offline discussion, I realized that there's
  a very simple example of the difference between hypermedia and data.

  Here's an example of "data", as you might see in a document-centric
  use of SOAP;

  <invoice>
   <item productid="439843434"/>
   <item productid="348787492"/>
   ...
  </invoice>

  Here's the hypermedia version of that;

  <invoice>
   <item productid="http://someco.example.org/product/439843434"/>
   <item productid="http://someco.example.org/product/348787492"/>
   ...
  </invoice>

  MB
  --
  Mark Baker.   Ottawa, Ontario, CANADA.        http://www.markbaker.ca
  Web architecture consulting, technical reports, evaluation & analysis