Loading ...
Sorry, an error occurred while loading the content.

Resources as Orange Apples

Expand Messages
  • Eric J. Bowman
    My friends have asked me to attempt to explain REST to them in terms they can understand. Which means I can t use the word semantics , basically. ;) I
    Message 1 of 17 , Aug 23, 2006
    • 0 Attachment
      My friends have asked me to attempt to explain REST to them in terms they can
      understand. Which means I can't use the word "semantics", basically. ;) I
      thought it best to use analogy instead of software-architecture examples, for
      starters my primary concern is explaining "Resource" in terms of basic set
      theory by sticking with apples and oranges.

      I've come up with what I believe to be a good analogy to bridge the gap, and
      I have a friend or two willing to write the copy of the final result with
      vastly reduced usage of the word "semantics" in an effort to make me
      comprehensible to others. :) We'll have a running conversation between
      "Captain Obvious", who pulls an orange out of a box of apples and calls it an
      orange, and "Mr. Stubborn" who insists that since it comes from a box of
      apples it must be an apple.

      I would like some feedback on the technical correctness of the analogy,
      hopefully without sidetracking into the possibility of orange, pine or even
      horse apples at every step of the way by remembering the intended audience --
      lay terms is the goal. I think everyone here is familiar with where the
      quotes come from, I hacked 'em up a bit though:

      >
      > 5.2.1.1 Resources and Resource Identifiers
      >
      > The key abstraction of information in REST is a esource. Any information
      > that can be named can be a resource: a document or image, a temporal
      > service (e.g. "today's weather in Los Angeles"), a collection of other
      > resources, a non-virtual object (e.g. a person), and so on. In other
      > words, any concept that might be the target of an author's hypertext
      > reference must fit within the definition of a resource.
      >

      The resource this example identifies is "a box of apples". Since a resource
      is a set (though it may have only one member) and since this set implies
      members must be apples, any dereferenceable target in the box must be an
      apple. Since this is only a conceptual mapping we don't need to specify what
      type of apples may be contained in the box.

      >
      > A resource is a conceptual mapping to a set of entities, not the entity
      > that corresponds to the mapping at any particular point in time.
      >

      The entities in this example are individual apples. Older apples go bad or
      get eaten and newer apples take their place. The resource is always "a box
      of apples", it does not become "a box of rotten apples" if a rotten apple is
      dereferenced.

      >
      > More precisely, a resource R is a temporally varying membership function
      > MR(t), which for time t maps to a set of entities, or values, which are
      > equivalent.
      >

      Over time, we may have all sorts of different apples coming into and going
      out of our box of apples. The set is limited to the apples in the box, but
      the number and types of apples represented in the box does not change the
      definition of "box of apples". If an object inside the box does not fit with
      the description of the contents of the box then that object simply does not
      belong inside that box -- oranges are not allowed.

      >
      > The values in the set may be resource representations and/or resource
      > identifiers. A resource can map to the empty set, which allows
      > references to be made to a concept before any realization of that
      > concept exists...
      >

      Just because we have a container we want to label "box of apples" does not
      imply that it must first contain any apples before we can label it. It may be
      empty. The "box of apples" might also just contain pictures of types of
      apples. So long as having a picture of an apple inside a "box of apples"
      doesn't change the meaning of "box of apples" we're OK, and we never said it
      was a "box of fresh apples".

      >
      > Some resources are static in the sense that, when examined at any time
      > after their creation, they always correspond to the same value set.
      >

      If we have a picture of an apple which identifies the bin within our box set
      aside for apples of that variety, we don't need to change it regardless of
      how often that type of apple comes and goes, even if we run out of stock.
      The picture of a Red Delicious apple inside our apple box is static. It is
      not a Red Delicious apple, a resource identifier which corresponds to a
      different apple each time.

      >
      > Others have a high degree of variance in their value over time... For
      > example, the "authors' preferred version" of an academic paper... These
      > are two distinct resources, even if they both map to the same value at
      > some point in time.
      >

      The "Apple of the Month" resource is an identifier, much like a "picture of
      an apple" is an identifier, neither are actually apples. As long as the
      picture of which apple is featured varies no more or less than once each
      month, the semantics of this resource identifier are static because it is
      never equal to "a Red Delicious apple" even when that variant is the Apple of
      the Month, nor is it equal to "still January, 1998's Apple of the Month".

      >
      > The only thing that is required to be static for a resource is the
      > semantics of the mapping, since the semantics is what distinguishes one
      > resource from another.
      >

      -----------------
      In the spirit of Chemistry's "Maxwell's Demon" and John Muir's "The Complete
      Idiot's Guide to Repairing Your Volkswagen":

      Captain Obvious: Sir, this would appear to be an orange!

      Mr. Stubborn: Why would you say that? It came out of an apple box!

      ...And so on and so forth a bit, the previous Fielding quote is repeated at
      the end with an explanation. Under development...

      [1] http://www.iwdn.net/images/smilies/paul_h_style/icon_obvious.gif
      [2] http://www.iwdn.net/images/smilies/paul_h_style/icon_stubborn.gif

      Those guys have been around for a while along with some others...
      -----------------

      >
      > This abstract definition of a resource enables key features of the Web
      > architecture. First, it provides generality by encompassing many sources
      > of information without artificially distinguishing them by type or
      > implementation.
      >

      We don't have to limit our options by calling our box a "box of Red Delicious
      apples". More importantly, we aren't actually prohibited from mixing apples
      with oranges, since some oranges can also be a type of apple there would be
      an artificial distinction imposed by excluding oranges from our box
      altogether. Good thing we didn't label our resource a "box of Apples -- no
      oranges allowed" or putting orange apples (even if they're just apples which
      happen to be orange-colored) inside the box would be a problem, instead we
      have provided generality with "box of apples".

      http://en.wikipedia.org/wiki/Apples_and_oranges#Oranges_as_a_type_of_apple

      >
      > Second, it allows late binding of the reference to a representation,
      > enabling content negotiation to take place based on characteristics of
      > the request.
      >

      A guy walks into the apple bar, the waitress (Connie Neg) spots him and says,
      "Ya want the usual, hon?" and fetches him his preferred variety, a Golden
      Delicious apple. "You ready to order, sugar?" she asks the next patron.
      "Yeah, I think I'll just have your special." he gets a Red Delicious, since
      it's Apple of the Month. When you want an apple, you just have to go to the
      apple bar, you don't need to decide what type of apple you actually want (or
      even what you want to do with it once you have it -- I may wind up feeding it
      to my neighbor's horse) until you get there and see what they have.

      (Also, for those following the orthogonally-related discussion, you can't
      send Connie down the street to Barney's house when Fred shows up and asks her
      for Barney's apple so why give Connie a key in the first place? If Barney
      asks Connie to go get his apple instead of one she has at the apple bar she
      should say, "Get lost, I'm busy here." Let Fred and Barney worry about
      hiding and finding any apples they don't intend for public consumption. This
      is certainly beyond Connie's job description. If Fred or Barney want a
      specific type of private apple they can negotiate with Wilma or Betty when
      they get home. -1 service doc.)

      >
      > Finally, it allows an author to reference the concept rather than some
      > singular representation of that concept, thus removing the need to
      > change all existing links whenever the representation changes (assuming
      > the author used the right identifier).
      >

      If we've designed the Apple of the Month function properly, we just change
      the picture of the apple on the placard. If we've designed it poorly, we need
      to move the old apples out of the special Apple of the Month bin at the end
      of each month to make way for the new variety and decide how to sort our
      newly-featured apple into two bins for one month, instead of just
      (re)directing people to the existing bin of the desired variety temporarily.

      >
      > REST uses a resource identifier to identify the particular resource
      > involved in an interaction between components. REST connectors provide a
      > generic interface for accessing and manipulating the value set of a
      > resource, regardless of how the membership function is defined or the
      > type of software that is handling the request.
      >

      The only thing anyone needs to manipulate an apple inside a box of apples is
      whatever they would normally pick up, deposit, bite or smash an apple with.
      Regardless of which employee is putting new apples into the box or which type
      of apples are involved, the interface is still manual labor.

      >
      > The naming authority that assigned the resource identifier, making it
      > possible to reference the resource, is responsible for maintaining the
      > semantic validity of the mapping over time (i.e., ensuring that the
      > membership function does not change).
      >

      If you label a placard "Apple of the Month" and you aren't responsible enough
      to change the picture and the bin it is on each month, or get a lackey
      (script) to do it, then you're a slacker and you have broken the semantic
      validity of your identifier (and most likely your website if you think you're
      implementing REST). If you tell people your box contains apples, don't fill
      it with oranges every third month and tell people that makes it temporarily a
      box of oranges.

      >
      > The only thing that is required to be static for a resource is the
      > semantics of the mapping, since the semantics is what distinguishes one
      > resource from another.
      >

      If you want people to be able to tell the difference between your apples and
      your oranges then don't mix your apples with your oranges. If someone wonders
      whether or not your orange apples are actually citrus fruits, you can point
      them to a box labeled "citrus fruit" which may not help if they're looking
      for oranges but certainly clarifies that you have a type of apple that is
      orange. If nobody cares whether they dereference an apple or an orange then
      label it a "box of fruit".

      -Eric
    • Chris Burdess
      ... I think this is wrong. A resource MAY or MAY NOT be a container. A container is a kind of resource that contains (aggregates) other resources: It may
      Message 2 of 17 , Aug 24, 2006
      • 0 Attachment
        Eric J. Bowman wrote:
        > ... a resource
        > is a set (though it may have only one member) ...

        I think this is wrong.

        A resource MAY or MAY NOT be a container. A container is a kind of
        resource that contains (aggregates) other resources:
      • Eric J. Bowman
        Good catch. How about this? Since a resource is a set (though it may have only one, or even zero, members) and... Yeah, that part needs some work, thanks.
        Message 3 of 17 , Aug 24, 2006
        • 0 Attachment
          Good catch. How about this?

          "Since a resource is a set (though it may have only one, or even zero,
          members) and..."

          Yeah, that part needs some work, thanks.

          -Eric

          >-----Original Message-----
          >From: Chris Burdess [mailto:dog@...]
          >Sent: Thursday, August 24, 2006 01:37 AM
          >To: eric@...
          >Cc: rest-discuss@yahoogroups.com
          >Subject: Re: [rest-discuss] Resources as Orange Apples
          >
          >Eric J. Bowman wrote:
          >> ... a resource
          >> is a set (though it may have only one member) ...
          >
          >I think this is wrong.
          >
          >A resource MAY or MAY NOT be a container. A container is a kind of
          >resource that contains (aggregates) other resources:
          >
          >
        • Jon Hanna
          ... A resource is not necessarily a set. It could be a set, it could also be something else (e.g., an apple). Furhter,
          Message 4 of 17 , Aug 25, 2006
          • 0 Attachment
            Eric J. Bowman wrote:
            > Good catch. How about this?
            >
            > "Since a resource is a set (though it may have only one, or even zero,
            > members) and..."
            >
            > Yeah, that part needs some work, thanks.

            A resource is not necessarily a set. It could be a set, it could also be
            something else (e.g., an apple).

            Furhter,
            http://en.wikipedia.org/wiki/Apples_and_oranges#Oranges_as_a_type_of_apple
            doesn't really make it okay to put oranges where "apples" is on the
            label, indeed it would be pushing it to put oranges where "pomum
            aurantium" is labelled.
          • Eric J. Bowman
            ... I think a resource, or a URI, is always a box (or set). The resource is never an apple, only the concept of an apple. If there is no apple, the box is
            Message 5 of 17 , Aug 25, 2006
            • 0 Attachment
              >
              >A resource is not necessarily a set. It could be a set, it could also be
              >something else (e.g., an apple).
              >

              I think a resource, or a URI, is always a box (or set). The resource is never
              an apple, only the concept of an apple. If there is no apple, the box is
              empty -- that's the null set i.e. a 404. I think the actual apple itself is
              always a representation of the concept of an apple.

              The analogy really breaks down if we insist that "an apple" is itself a
              resource, because we're dealing with the Internet here. If we have a nonzero
              number of apples we can never be certain how many apples we have, and of
              course if someone were to eat an apple it wouldn't exactly deplete our stock.

              If I'm doing version control I may also have some rotten apples in my box,
              otherwise all rotten apples are cached externally to my box until a fresh
              apple takes the place of each (revalidation). As soon as the box contains
              one apple that apple multiplies like rabbits. A resource is a concept not an
              object, an object is always a representation of its concept.

              If my box isn't identifying the null set it must always contain either at
              least one (thing called an) apple, or one and only one pointer to some other
              box of apples. If I want my box of apples to directly identify another box
              of apples (author's preferred version) then it may contain one redirection
              pointer.

              If I want my box of apples to directly identify many other boxes of apples
              (reader's preferred versions) and it contains multiple redirection pointers,
              it has ceased to be a box of apples and has become a box of boxes. The
              apples in those other boxes may be the same, but they are not equivalent as
              they are members of different sets.

              >
              >Furhter,
              >http://en.wikipedia.org/wiki/Apples_and_oranges#Oranges_as_a_type_of_apple
              >doesn't really make it okay to put oranges where "apples" is on the
              >label, indeed it would be pushing it to put oranges where "pomum
              >aurantium" is labelled.
              >

              I would agree, had I implied that my box contained apples-as-fruits, which
              maybe I did. What if we call it "a box of things called apples" instead? If
              the pictures inside are shown to a reasonable person who is asked, "what are
              these" the response would not be "photographs" it would be "apples" or
              "pictures of apples".

              Either response satisfies "things called apples" and so does "pomum
              aurantium".

              It's hard to illustrate the point that if I wanted to imply that my box was
              only full of what people commonly know as an apple but I also had some pomum
              aurantiums laying around, that those should go in a box labeled "oranges".
              I'm hoping my re-writer can do a better job.

              -Eric
            • Walden Mathews
              Eric, I think this box of apples analogy is confusing. An individual apple may represent the apples concept, but this can t have much to do with REST. REST
              Message 6 of 17 , Aug 25, 2006
              • 0 Attachment
                Eric,

                I think this box of apples analogy is confusing. An individual apple
                may represent the "apples" concept, but this can't have much to do
                with REST. REST representations are bit streams.

                In any event, if REST newbies want to understand resource as a
                mapping of time to representations, it is probably more intuitive to
                demonstrate that with www.weather.com. I don't think of the weather
                in my town as a box of anything. It's just the weather. I look again;
                it has changed.

                People who need to understand REST are going to be computer
                scientists. It is reasonable to expect them to understand mappings
                whose domain is time and whose range is bit streams.

                Anyway, if you do decide to pursue this, I hope you will find a way
                to do it that does not begin by planting the idea that REST somehow
                condones container-containee inconsistency. There is really no
                basis for that.

                Walden

                ----- Original Message -----
                From: "Eric J. Bowman" <eric@...>
                To: "Jon Hanna" <jon@...>
                Cc: <rest-discuss@yahoogroups.com>
                Sent: Friday, August 25, 2006 7:17 PM
                Subject: Re: [rest-discuss] Resources as Orange Apples


                : >
                : >A resource is not necessarily a set. It could be a set, it could also be
                : >something else (e.g., an apple).
                : >
                :
                : I think a resource, or a URI, is always a box (or set). The resource is
                never
                : an apple, only the concept of an apple. If there is no apple, the box is
                : empty -- that's the null set i.e. a 404. I think the actual apple itself
                is
                : always a representation of the concept of an apple.
                :
                : The analogy really breaks down if we insist that "an apple" is itself a
                : resource, because we're dealing with the Internet here. If we have a
                nonzero
                : number of apples we can never be certain how many apples we have, and of
                : course if someone were to eat an apple it wouldn't exactly deplete our
                stock.
                :
                : If I'm doing version control I may also have some rotten apples in my box,
                : otherwise all rotten apples are cached externally to my box until a fresh
                : apple takes the place of each (revalidation). As soon as the box contains
                : one apple that apple multiplies like rabbits. A resource is a concept not
                an
                : object, an object is always a representation of its concept.
                :
                : If my box isn't identifying the null set it must always contain either at
                : least one (thing called an) apple, or one and only one pointer to some
                other
                : box of apples. If I want my box of apples to directly identify another
                box
                : of apples (author's preferred version) then it may contain one redirection
                : pointer.
                :
                : If I want my box of apples to directly identify many other boxes of apples
                : (reader's preferred versions) and it contains multiple redirection
                pointers,
                : it has ceased to be a box of apples and has become a box of boxes. The
                : apples in those other boxes may be the same, but they are not equivalent
                as
                : they are members of different sets.
                :
                : >
                : >Furhter,
                :
                >http://en.wikipedia.org/wiki/Apples_and_oranges#Oranges_as_a_type_of_apple
                : >doesn't really make it okay to put oranges where "apples" is on the
                : >label, indeed it would be pushing it to put oranges where "pomum
                : >aurantium" is labelled.
                : >
                :
                : I would agree, had I implied that my box contained apples-as-fruits, which
                : maybe I did. What if we call it "a box of things called apples" instead?
                If
                : the pictures inside are shown to a reasonable person who is asked, "what
                are
                : these" the response would not be "photographs" it would be "apples" or
                : "pictures of apples".
                :
                : Either response satisfies "things called apples" and so does "pomum
                : aurantium".
                :
                : It's hard to illustrate the point that if I wanted to imply that my box
                was
                : only full of what people commonly know as an apple but I also had some
                pomum
                : aurantiums laying around, that those should go in a box labeled "oranges".
                : I'm hoping my re-writer can do a better job.
                :
                : -Eric
                :
                :
                :
                :
                :
                : __________ NOD32 1.1725 (20060825) Information __________
                :
                : This message was checked by NOD32 antivirus system.
                : http://www.eset.com
                :
                :
              • Eric J. Bowman
                ... That point about representations is well-taken. But I also think using varieties of apples is a good way to explain variant . ... The basic concept I am
                Message 7 of 17 , Aug 25, 2006
                • 0 Attachment
                  >
                  >I think this box of apples analogy is confusing. An individual apple
                  >may represent the "apples" concept, but this can't have much to do
                  >with REST. REST representations are bit streams.
                  >

                  That point about representations is well-taken. But I also think using
                  varieties of apples is a good way to explain "variant".

                  >
                  >In any event, if REST newbies want to understand resource as a
                  >mapping of time to representations, it is probably more intuitive to
                  >demonstrate that with www.weather.com. I don't think of the weather
                  >in my town as a box of anything. It's just the weather. I look again;
                  >it has changed.
                  >

                  The basic concept I am trying to portray is that a resource is a set, in fact
                  that is what Dr. Fielding's dissertation calls it:

                  "[A] resource... maps to a set of entities..."

                  A friend of mine brought up the notion of XML namespaces, how is that a set.
                  Well, a 404 response may not make it a null set, because there still may be a
                  description of that namespace out there even if the identifier doesn't locate
                  it. A namespace URI is still a set whose membership function is whatever
                  document describes that namespace.

                  >
                  >People who need to understand REST are going to be computer
                  >scientists. It is reasonable to expect them to understand mappings
                  >whose domain is time and whose range is bit streams.
                  >

                  I couldn't disagree more. "What is REST" and related questions are popping
                  up more and more frequently amongst lay web developers who are increasingly
                  standards-conscious. After years spent un-learning a variety of bad habits
                  (like table-based layouts instead of CSS) which were once mainstream many of
                  us are asking, "OK, enough already, what is the right way?" I know lots of
                  non-computer-scientist types who are experienced application developers using
                  PHP and such, who are coming to understand that MVC isn't the best way, but
                  need practical assistance designing URIs correctly.

                  Here's what Sleepycat Software has to say on the issue:

                  "[S]ites are maturing, becoming more complex and more flexible. This richness
                  comes at a price; the data-model required to represent the dynamic nature of
                  these next generation sites requires a computer science degree. As sites have
                  grown in complexity, the number of programmers able to build the sites has
                  decreased and site construction, infrastructure and maintenance costs have
                  gone up."

                  [1] http://www.sleepycat.com/newsletters/0502/a14_FebProdPHP.shtml

                  I disagree that understanding REST should require a degree in Computer
                  Science, but the reality described in that ad copy is motivating more
                  developers to look at REST for solutions to rein in escalating hosting costs.

                  >
                  >Anyway, if you do decide to pursue this, I hope you will find a way
                  >to do it that does not begin by planting the idea that REST somehow
                  >condones container-containee inconsistency. There is really no
                  >basis for that.
                  >

                  This is why I need a re-writer... That's exactly the notion I'm trying to
                  dispel by explaining _why_ "The only thing that is required to be static for
                  a resource is the semantics of the mapping, since the semantics is what
                  distinguishes one resource from another." I just thought "don't put oranges
                  in a box of apples" was oversimplifying...

                  This is the real challenge. I have trouble explaining this to my coder on a
                  daily basis and he does have a degree in Computer Science, just no practical
                  experience of anything but RPC-style development. I find it helpful to
                  abstract the REST concepts with him, too, particularly what is meant by "the
                  semantics of the mapping must be static".

                  -Eric

                  >
                  >Walden
                  >
                • Roy T. Fielding
                  ... The correct quote is a resource R is a temporally varying membership function MR(t), which for time t maps to a set of entities, or values, which are
                  Message 8 of 17 , Aug 28, 2006
                  • 0 Attachment
                    On Aug 25, 2006, at 6:09 PM, Eric J. Bowman wrote:
                    > The basic concept I am trying to portray is that a resource is a
                    > set, in fact
                    > that is what Dr. Fielding's dissertation calls it:
                    >
                    > "[A] resource... maps to a set of entities..."

                    The correct quote is

                    "a resource R is a temporally varying membership function MR(t), which
                    for time t maps to a set of entities, or values, which are equivalent.
                    The values in the set may be resource representations and/or resource
                    identifiers."

                    A resource is a membership function. A membership function is not a set.
                    The value of that function for a given time t is a set. The resource is
                    the continuity of those values over time, not the value at any given
                    instant in time.

                    Your analogy starts off on the wrong foot by talking about resources
                    in terms of how they might be implemented (a box of apples).

                    A better framework for an analogy is a double-sided wall of pigeon-hole
                    boxes, with doors, a button, and a label per box on each side. The
                    client side of the wall can only see the labels on their own side.
                    The server side of the wall can only see the labels on their own side.
                    When the client pushes a button, the button on the opposite side
                    lights up.
                    The server side then opens their door, places something corresponding to
                    their server-side label in the hole, and closes their door -- causing
                    the
                    corresponding client-side button to light up. The client then opens the
                    door, grabs what was placed in the hole, and closes their door.
                    Finally,
                    the client decides whether or not to change the label on their side of
                    the door based on what was received when the button was pushed. The
                    client has no idea what is behind the door or how the holes get filled.

                    "client" and "server" are only used here for a directional sense, so
                    variations an be made for writing (e.g., the client could place
                    something in the hole first and then push the button, or there
                    could be more than one type of button, etc.).

                    Now you can add apples and oranges to that framework and make an
                    analogy.


                    ....Roy
                  • Dave Pawson
                    ... Wonderful analogy Roy! Clear as water! regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk
                    Message 9 of 17 , Aug 28, 2006
                    • 0 Attachment
                      > A better framework for an analogy is a double-sided wall of pigeon-hole
                      > boxes, with doors, a button, and a label per box on each side.

                      Wonderful analogy Roy! Clear as water!



                      regards
                      --
                      Dave Pawson
                      XSLT XSL-FO FAQ.
                      http://www.dpawson.co.uk
                    • Eric J. Bowman
                      ... I hope I haven t given offense by editing your words. :-( ... You know this, I know this, everyone here should know this, but my audience consists of
                      Message 10 of 17 , Aug 29, 2006
                      • 0 Attachment
                        >>
                        >> "[A] resource... maps to a set of entities..."
                        >
                        >The correct quote is
                        >

                        I hope I haven't given offense by editing your words. :-(

                        >
                        >A resource is a membership function. A membership function is not a set.
                        >The value of that function for a given time t is a set. The resource is
                        >the continuity of those values over time, not the value at any given
                        >instant in time.
                        >

                        You know this, I know this, everyone here should know this, but my audience
                        consists of people who do not know this. The problem I have here, is how to
                        lead into _any_ analogy in a way which doesn't stop people here at the first
                        paragraph, yet also doesn't stop my intended audience at the very first
                        paragraph. Your dissertation and your analogy are "whole", but that's not
                        always the best strategy for teaching difficult concepts to those with only
                        an intermediate level of knowledge.

                        What I'm trying for is "whole-part-whole", since everyone's starting place is
                        the dissertation. I don't think those who fail to grasp it are incapable of
                        learning REST, I think they need some help, by breaking resource/
                        representation down into a simplified "part" which may be modeled using Venn
                        diagrams, which may then be used to build the knowledge level of the target
                        audience back up to "whole".

                        All I know about teaching comes from teaching people to swim, and what I
                        picked up as a student in my incomplete University education -- what formal
                        training I have is in Chemistry, but one of my Professors was Tom Cech (had
                        him when he won his Nobel), and I helped Igor Gamow test SUBA in CU's
                        competitive diving well. I managed rec centers back in those days and was
                        responsible for maintaining CU's pools (and occasionally the Zamboni) while I
                        was a student lifeguard.

                        Which is why I brought up Maxwell's Demon. In teaching Chemistry and
                        Physics, many advanced concepts are impossible to teach without having a
                        means to decrease entropy, in violation of the Second Law of Thermodynamics.
                        Maxwell's Demon is "allowed" to reduce entropy without being considered a
                        part of the system -- he may be busy but he does no work. Maxwell's Demon
                        and the concept of entropy have been applied to a variety of other subjects,
                        and I firmly believe that such a device is needed to teach REST, _because_ a
                        resource is a temporally varying membership function not a set.

                        Here, I'm creating a Maxwell's Demon by considering only one instant in time,
                        "removing entropy from the equation" so that the set being mapped by the
                        resource may be used to help explain what the resource is. What results, is
                        calling the resource the set for the purpose of describing the semantics of
                        its mapping. The Venn diagrams serve this purpose even if my analogy is
                        off. I'm not concerned about doing this, as using such a Demon doesn't
                        prevent any analogies, or explanations based on those analogies, from
                        introducing the "temporally varying membership function" bit when it's time
                        to work back to the "whole".

                        >
                        >Your analogy starts off on the wrong foot by talking about resources
                        >in terms of how they might be implemented (a box of apples).
                        >

                        Yes, it does, by design. With a copy of "How to Keep Your Volkswagen Alive:
                        A Manual of Step-by-Step Procedures for the Compleat Idiot", some tools and a
                        VW Beetle I can teach a 16-year-old how to set the timing on any vehicle with
                        a mechanical points-and-condenser ignition system, even a Zamboni. He'd be
                        helpless faced with a modern electronic ignition system with computer-
                        controlled variable timing -- that takes some advanced study.

                        The book I mention explains the concept of "internal-combustion automobile
                        engine" by considering one simplistic implementation, an air-cooled VW boxer
                        four. The procedures and explanations fundamentally apply to modern internal-
                        combustion auto engines, even the ones which seem laughable by today's
                        standards -- like setting the timing with a timing light, a wrench, and a
                        feeler guage for the "points". The marginalia cartoons are a classic touch.

                        Give me a Haynes manual, some tools, and a BMW V-12 and I can't teach a 16-
                        year-old a thing. I see a need for keeping it simple when explaining REST by
                        speaking of one simplistic implementation, which may be expanded upon in
                        further study, as my box of apples changes into an apple bar and a vending
                        machine in my examples. I don't think my vending machine example and your
                        double-sided wall of boxes are all that far apart that they couldn't be
                        modified into something useful for explaining REST, but I think the important
                        part is that the result be something familiar and recognizable to people.

                        >
                        >Now you can add apples and oranges to that framework and make an
                        >analogy.
                        >

                        Meaning no offense, but I could also teach someone how to use an adding
                        machine by sitting them down at a UNIVAC. ;-) Your example is certainly
                        superior to mine when considering this audience, but this audience is not my
                        target.

                        -Eric (AFK for a few days, sorry)

                        >
                        >....Roy
                        >
                      • Benjamin Carlyle
                        Eric, ... Resources are easy to explain. Resources are like objects. They demarcate application state in the same way as objects. The web is full of resources
                        Message 11 of 17 , Sep 9, 2006
                        • 0 Attachment
                          Eric,

                          On Thu, 2006-08-24 at 04:40 +0000, Eric J. Bowman wrote:
                          > My friends have asked me to attempt to explain REST to them in terms
                          > they can
                          > understand. Which means I can't use the word "semantics",
                          > basically. ;) I
                          > thought it best to use analogy instead of software-architecture
                          > examples, for
                          > starters my primary concern is explaining "Resource" in terms of basic
                          > set
                          > theory by sticking with apples and oranges.

                          Resources are easy to explain. Resources are like objects. They
                          demarcate application state in the same way as objects. The web is full
                          of resources like a java program is full of objects. The main difference
                          is in how you interact with them.

                          First of all, resources have only one type. We don't need baseclasses or
                          interface classes. We only have resources. Resources can be found using
                          a single identifier scheme. Think pointers. Once you have a pointer to
                          the resource, you can call invoke methods on it. These methods might be
                          issued directly to the resource, or might go through a proxy of some
                          kind.

                          Resources only have a limited set of methods, and each of these methods
                          are based around transfering a document per invocation rather than a
                          parameter list. If you were to ascribe member variables (or state, or
                          just plain information) to your object, they would form the schema
                          behind the documents you transfer. This schema can be transferred in
                          several forms (representations). You could return a HTML document which
                          listed out information held in your object. You could return an image,
                          or some othe form of your state... but each representation conveys the
                          same information. Updates should take on one of these forms and update
                          the object atomically, rather than setting the value of one variable
                          after the other over several invocations.

                          All representations returned by a resource should be standard, ideally
                          understood by every relevant piece of software in the world.

                          So, you have a uniform resource locator scheme (a pointer). You have
                          uniform methods that accept and/or return a document and tell you which
                          encoding is used in the document. Each document is of a standard type.
                          Because everything looks the same, sometimes you need extra resources to
                          represent different facets of what might conceptually have been one
                          object in a less constrained environment.

                          That's REST without the oranges.

                          Concrete example?

                          Client -> Server
                          GET http://example.com/lightbulb HTTP/1.1

                          Server -> Client
                          HTTP/1.1 200 OK
                          Content-Type: text/plain

                          on

                          Client -> Server
                          PUT http://example.com/lightbulb HTTP/1.1
                          Content-Type: text/plain

                          off

                          Server -> Client
                          HTTP/1.1 200 OK

                          See also
                          http://en.wikipedia.org/wiki/Representational_State_Transfer
                          http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage

                          Benjamin.
                        • S. Mike Dierken
                          Most excellent. Add this to the REST Wiki, everybody will benefit.
                          Message 12 of 17 , Sep 9, 2006
                          • 0 Attachment
                            Most excellent.
                            Add this to the REST Wiki, everybody will benefit.

                            > -----Original Message-----
                            > From: rest-discuss@yahoogroups.com
                            > [mailto:rest-discuss@yahoogroups.com] On Behalf Of Benjamin Carlyle
                            > Sent: Saturday, September 09, 2006 10:53 PM
                            > To: eric@...
                            > Cc: rest-discuss@yahoogroups.com
                            > Subject: Re: [rest-discuss] Resources as Orange Apples
                            >
                            > Eric,
                            >
                            > On Thu, 2006-08-24 at 04:40 +0000, Eric J. Bowman wrote:
                            > > My friends have asked me to attempt to explain REST to them
                            > in terms
                            > > they can understand. Which means I can't use the word "semantics",
                            > > basically. ;) I thought it best to use analogy instead of
                            > > software-architecture examples, for starters my primary concern is
                            > > explaining "Resource" in terms of basic set theory by sticking with
                            > > apples and oranges.
                            >
                            > Resources are easy to explain. Resources are like objects.
                            > They demarcate application state in the same way as objects.
                            > The web is full of resources like a java program is full of
                            > objects. The main difference is in how you interact with them.
                            >
                            > First of all, resources have only one type. We don't need
                            > baseclasses or interface classes. We only have resources.
                            > Resources can be found using a single identifier scheme.
                            > Think pointers. Once you have a pointer to the resource, you
                            > can call invoke methods on it. These methods might be issued
                            > directly to the resource, or might go through a proxy of some kind.
                            >
                            > Resources only have a limited set of methods, and each of
                            > these methods are based around transfering a document per
                            > invocation rather than a parameter list. If you were to
                            > ascribe member variables (or state, or just plain
                            > information) to your object, they would form the schema
                            > behind the documents you transfer. This schema can be
                            > transferred in several forms (representations). You could
                            > return a HTML document which listed out information held in
                            > your object. You could return an image, or some othe form of
                            > your state... but each representation conveys the same
                            > information. Updates should take on one of these forms and
                            > update the object atomically, rather than setting the value
                            > of one variable after the other over several invocations.
                            >
                            > All representations returned by a resource should be
                            > standard, ideally understood by every relevant piece of
                            > software in the world.
                            >
                            > So, you have a uniform resource locator scheme (a pointer).
                            > You have uniform methods that accept and/or return a document
                            > and tell you which encoding is used in the document. Each
                            > document is of a standard type.
                            > Because everything looks the same, sometimes you need extra
                            > resources to represent different facets of what might
                            > conceptually have been one object in a less constrained environment.
                            >
                            > That's REST without the oranges.
                            >
                            > Concrete example?
                            >
                            > Client -> Server
                            > GET http://example.com/lightbulb HTTP/1.1
                            >
                            > Server -> Client
                            > HTTP/1.1 200 OK
                            > Content-Type: text/plain
                            >
                            > on
                            >
                            > Client -> Server
                            > PUT http://example.com/lightbulb HTTP/1.1
                            > Content-Type: text/plain
                            >
                            > off
                            >
                            > Server -> Client
                            > HTTP/1.1 200 OK
                            >
                            > See also
                            > http://en.wikipedia.org/wiki/Representational_State_Transfer
                            > http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
                            >
                            > Benjamin.
                            >
                            >
                            >
                            >
                            >
                            > Yahoo! Groups Links
                            >
                            >
                            >
                            >
                            >
                            >
                            >
                            >
                          • Roy T. Fielding
                            ... Editing is fine if you don t change the meaning in the process. ... I don t think you were even close. If you want to teach someone about web
                            Message 13 of 17 , Sep 10, 2006
                            • 0 Attachment
                              On Aug 29, 2006, at 3:36 AM, Eric J. Bowman wrote:
                              > >>
                              > >> "[A] resource... maps to a set of entities..."
                              > >
                              > >The correct quote is
                              > >
                              >
                              > I hope I haven't given offense by editing your words. :-(

                              Editing is fine if you don't change the meaning in the process.

                              > >A resource is a membership function. A membership function is not
                              > a set.
                              > >The value of that function for a given time t is a set. The
                              > resource is
                              > >the continuity of those values over time, not the value at any given
                              > >instant in time.
                              > >
                              >
                              > You know this, I know this, everyone here should know this, but my
                              > audience
                              > consists of people who do not know this. The problem I have here,
                              > is how to
                              > lead into _any_ analogy in a way which doesn't stop people here at
                              > the first
                              > paragraph, yet also doesn't stop my intended audience at the very
                              > first
                              > paragraph. Your dissertation and your analogy are "whole", but
                              > that's not
                              > always the best strategy for teaching difficult concepts to those
                              > with only
                              > an intermediate level of knowledge.
                              >
                              > What I'm trying for is "whole-part-whole", since everyone's
                              > starting place is
                              > the dissertation. I don't think those who fail to grasp it are
                              > incapable of
                              > learning REST, I think they need some help, by breaking resource/
                              > representation down into a simplified "part" which may be modeled
                              > using Venn
                              > diagrams, which may then be used to build the knowledge level of
                              > the target
                              > audience back up to "whole".

                              I don't think you were even close. If you want to teach someone about
                              web architecture, then you can give concrete examples that some people
                              may find easier to understand. If you want to teach someone about REST,
                              then you have to at least be consistent with the principles of REST
                              as they have been defined. All you are teaching people is a very
                              confused model of fruit placement, and there is zero chance that they
                              will learn anything meaningful about REST when your whole example
                              ignores time.

                              Time is the single most important aspect of REST as an architectural
                              style. All of the constraints are designed to moderate the effects
                              of a changing environment over time, enable independent evolution,
                              and reduce latency. All of the benefits from REST-based design can
                              only be seen when a system is exposed to change over time.

                              REST is not about design-in-the-small. It can't be taught by looking
                              at a single implementation at an instant in time any more than you can
                              teach swimming without talking about the nature of water. The analogy
                              has to be representative of the subject being taught.

                              > Yes, it does, by design. With a copy of "How to Keep Your
                              > Volkswagen Alive:
                              > A Manual of Step-by-Step Procedures for the Compleat Idiot", some
                              > tools and a
                              > VW Beetle I can teach a 16-year-old how to set the timing on any
                              > vehicle with
                              > a mechanical points-and-condenser ignition system, even a Zamboni.
                              > He'd be
                              > helpless faced with a modern electronic ignition system with computer-
                              > controlled variable timing -- that takes some advanced study.
                              >
                              > The book I mention explains the concept of "internal-combustion
                              > automobile
                              > engine" by considering one simplistic implementation, an air-cooled
                              > VW boxer
                              > four. The procedures and explanations fundamentally apply to modern
                              > internal-
                              > combustion auto engines, even the ones which seem laughable by today's
                              > standards -- like setting the timing with a timing light, a wrench,
                              > and a
                              > feeler guage for the "points". The marginalia cartoons are a
                              > classic touch.

                              That's because a VW Beetle contains an implementation of an internal
                              combustion engine. You can learn a lot by looking at an example of
                              an abstract concept. However, as I was saying, a resource is not a
                              box of apples. It isn't even close. At most you could say that a
                              resource is a store where you can expect to buy apples. At least then
                              the student will understand the value of it being a resource: a source
                              of future representations, not a specific set of representations at
                              any given instant in time.

                              ....Roy
                            • Dave Pawson
                              ... ... I think I get that. Continuing this example, although the store has apples today, it may not have any tomorrow. The representation available
                              Message 14 of 17 , Sep 10, 2006
                              • 0 Attachment
                                On 10/09/06, Roy T. Fielding <fielding@...> wrote:

                                >
                                > Time is the single most important aspect of REST as an architectural
                                > style. All of the constraints are designed to moderate the effects
                                > of a changing environment over time, enable independent evolution,
                                > and reduce latency. All of the benefits from REST-based design can
                                > only be seen when a system is exposed to change over time.

                                <snip/>


                                .... However, as I was saying, a resource is not a
                                > box of apples. It isn't even close. At most you could say that a
                                > resource is a store where you can expect to buy apples. At least then
                                > the student will understand the value of it being a resource: a source
                                > of future representations, not a specific set of representations at
                                > any given instant in time.

                                I think I get that. Continuing this example,
                                although the store has apples today, it may not have any tomorrow.
                                The representation available from the resource changes over time
                                in the same way that a web page content changes over time and hence
                                the web page is a resource.
                                Is that along the right lines?

                                regards




                                --
                                Dave Pawson
                                XSLT XSL-FO FAQ.
                                http://www.dpawson.co.uk
                              • Eric J. Bowman
                                ... Fair enough. Please realize that my understanding of resources and representations in REST came about through the application of set theory (using those
                                Message 15 of 17 , Sep 10, 2006
                                • 0 Attachment
                                  >
                                  >I don't think you were even close. If you want to teach someone about
                                  >web architecture, then you can give concrete examples that some people
                                  >may find easier to understand... The analogy has to be representative of
                                  >the subject being taught... If you want to teach someone about REST,
                                  >then you have to at least be consistent with the principles of REST
                                  >as they have been defined.
                                  >

                                  Fair enough. Please realize that my understanding of resources and
                                  representations in REST came about through the application of set theory
                                  (using those diagrams) to my own projects, which make heavy use of content
                                  negotiation and redirection. If the subject being taught is set theory, then
                                  apples and oranges are a consistent analogy. I only intended for the analogy
                                  to apply to resources and representations, not REST as a whole.

                                  >
                                  >REST is not about design-in-the-small. It can't be taught by looking
                                  >at a single implementation at an instant in time any more than you can
                                  >teach swimming without talking about the nature of water.
                                  >

                                  If I understand your point, analogies which focus on one static set risk
                                  losing critical aspects of REST overall. I've found a method/tool which
                                  helps me analyze the set-related issues I have trouble understanding. It has
                                  nothing to do with software architecture, only URI design and response-code
                                  implementation. So, _any_ analogy derived from this particular "part" would
                                  have limited value to the "whole". OK, I can see that. I'm done with
                                  attempts at REST analogies for the forseeable future.

                                  >
                                  >Time is the single most important aspect of REST as an architectural
                                  >style. All of the constraints are designed to moderate the effects
                                  >of a changing environment over time, enable independent evolution,
                                  >and reduce latency. All of the benefits from REST-based design can
                                  >only be seen when a system is exposed to change over time.
                                  >

                                  I still have a Maxwell's Demon with my use of diagrams, but I'll just say it
                                  reduces entropy, rather than freezes time, which is a more apt description of
                                  any form of "site map". The purpose is to model three "concrete" constraints
                                  I derived from "R is a temporally varying membership function MR(t), which
                                  for time t maps to a set of entities, or values, which are equivalent" which
                                  have proven extremely helpful to me over the past couple of years.

                                  My aspirations to a degree in Chemistry were doomed from the start -- I
                                  always assumed I would be able to learn advanced Calculus but this proved
                                  false. The final year of undergraduate study is Physical Chemistry, i.e.
                                  Kinetics, which is of course all Calculus. But Organic Chemistry (not that I
                                  remember much of it) was a breeze for me.

                                  There are multiple methods of writing an Organic Chem formula, depending on
                                  need, and molecules may be diagrammed on paper or snapped together with those
                                  3-D model sets (gumdrops and toothpicks, if you took Chem in High School).
                                  Yeah, I like to model stuff with diagrams, it's how I learn. I'm a pen-and-
                                  paper guy, though, so this is my first effort to describe what I'm up to with
                                  my REST modeling and publish it.

                                  >
                                  >That's because a VW Beetle contains an implementation of an internal
                                  >combustion engine. You can learn a lot by looking at an example of
                                  >an abstract concept.
                                  >

                                  Which is why I think there's some value in my modeling, aside from any
                                  analogy. Using the document located at the last URL I posted (in response to
                                  input from this thread), I was able to determine why my analogy was a bit
                                  confused with some help from a few of you on-list, plus Walden Matthews and
                                  my friend Michaeljohn (who didn't like the apples and oranges analogy either)
                                  off-list. I understand the mistake I was making and have learned from it.

                                  We're using Resin Pro as our httpd. Clients and intermediary caches only
                                  receive responses from the server connector if we bypass the response filter
                                  we use in our servlet's chain to set the cache-control headers. Otherwise,
                                  all responses come from the cache connector located on the interface to the
                                  server connector. I was erroneously seeing that cache connector as the
                                  "origin server" but it isn't. Working that out led to this:

                                  [1] http://canuck.bisonsystems.net/dev/rest/cache_alias.html

                                  Nic Ferrier was asking me a while back what I meant by my notion of a "cache
                                  alias". Simply put, from the perspective of the cache connector, in the
                                  presence of VARY and cache-control response headers each representation
                                  received from the server connector becomes a resource with its own set of
                                  representations, one for each combination of the varied request headers it
                                  encounters. MJ reserved judgment on the technical merits, but said he did
                                  understand what I'm saying, albeit he has a better idea of the context. I
                                  haven't shared [1] with anyone else yet.

                                  -Eric
                                • Roy T. Fielding
                                  ... Not exactly. A resource is a conceptual mapping. That mapping may be as abstract as the Apple Store or as concrete as a single apple that was at one
                                  Message 16 of 17 , Sep 10, 2006
                                  • 0 Attachment
                                    On Sep 10, 2006, at 1:04 AM, Dave Pawson wrote:
                                    > although the store has apples today, it may not have any tomorrow.
                                    > The representation available from the resource changes over time
                                    > in the same way that a web page content changes over time and hence
                                    > the web page is a resource.
                                    > Is that along the right lines?

                                    Not exactly. A resource is a conceptual mapping. That mapping may be
                                    as abstract as "the Apple Store" or as concrete as a single apple that
                                    was at one time in a box at the Apple Store. A resource is largely
                                    defined by what you make of it. So it is possible that the
                                    representations of a given resource do not change over time.
                                    A web site is a resource. A web page (the conceptual page expected
                                    by a user when they follow a hypertext link) is a resource.
                                    So are each of the in-line elements that make up that page, as
                                    are (at least for the server) all of the files/programs used to
                                    construct the content of that page. Each of those are separate
                                    resources in their own right.

                                    But knowing what the "resource" is does not teach much about REST,
                                    since REST is designed to hide that information from clients.

                                    Lots of people complain about the definition, largely because
                                    it seems so nebulous and effectively anything could be a resource.
                                    What they don't understand is that allowing anything to be a resource
                                    is the goal, and REST describes how to build an architecture that
                                    can effectively manipulate anything even when the client has no
                                    idea what that thing actually may be. That's the point.

                                    If an application can accomplish the user's need of today in a
                                    way that is reusable by others, and without revealing much of
                                    anything about how it works, then there is a good chance that
                                    the implementation of how it works can evolve independently of
                                    the user and also that how the user makes use of that work can
                                    evolve independently from what was anticipated by the resource
                                    owner. Those are two of the goals of REST: independent evolvability
                                    and design-for-serendipity. There are other goals (e.g., scalability).

                                    ....Roy
                                  • Dave Pawson
                                    ... Mapping? From my minimal maths, I think of mappings from X to Y? How (if at all) do the range of resources in your examples relate to mappings please? Is
                                    Message 17 of 17 , Sep 10, 2006
                                    • 0 Attachment
                                      On 10/09/06, Roy T. Fielding <fielding@...> wrote:

                                      > Not exactly. A resource is a conceptual mapping. That mapping may be
                                      > as abstract as "the Apple Store" or as concrete as a single apple that
                                      > was at one time in a box at the Apple Store. A resource is largely
                                      > defined by what you make of it.
                                      Mapping? From my minimal maths, I think of mappings from
                                      X to Y? How (if at all) do the range of resources in your examples
                                      relate to mappings please? Is there a source & destination?


                                      <snip/>

                                      >
                                      > But knowing what the "resource" is does not teach much about REST,
                                      From the above examples I'm glad of that :-)
                                      > since REST is designed to hide that information from clients.



                                      > Lots of people complain about the definition, largely because
                                      > it seems so nebulous and effectively anything could be a resource.

                                      I could support that. You seem purposely to emphasise the
                                      abstract nature of resources. Is that primarily to emphasise
                                      the hiding of ...[information or resources] by an RESTful architecture?

                                      > What they don't understand is that allowing anything to be a resource
                                      > is the goal, and REST describes how to build an architecture that
                                      > can effectively manipulate anything even when the client has no
                                      > idea what that thing actually may be. That's the point.

                                      Does the software ideas of decoupling/data hiding have any place in such
                                      a description? That's what it sounds like to me.

                                      >
                                      > If an application can accomplish the user's need of today in a
                                      > way that is reusable by others, and without revealing much of
                                      > anything about how it works, then there is a good chance that
                                      > the implementation of how it works can evolve independently of
                                      > the user and also that how the user makes use of that work can
                                      > evolve independently from what was anticipated by the resource
                                      > owner.
                                      Again very much aligned with the ideas of data hiding? A consistant
                                      interface enables design change on either side without impact
                                      on the application.


                                      Those are two of the goals of REST: independent evolvability
                                      > and design-for-serendipity.

                                      :-) Design for serendipity (what-if programming?) tends to be expensive IMHO,
                                      though still a nice goal.

                                      The evolvability is the benefit I find most attractive.



                                      There are other goals (e.g., scalability).


                                      I do wish you'd do more of this plain English explanatory stuff Roy.

                                      Very much appreciated.

                                      regards
                                      --
                                      Dave Pawson
                                      XSLT XSL-FO FAQ.
                                      http://www.dpawson.co.uk
                                    Your message has been successfully submitted and would be delivered to recipients shortly.