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

Another "is this ReSTful" question

Expand Messages
  • Gary Shea
    Hi -- I m building a simple order management web service which allows an order app in the field to submit orders, allows factory-side apps to access orders by
    Message 1 of 24 , Jan 8, 2003
    • 0 Attachment
      Hi --

      I'm building a simple order management web service which allows an
      order app in the field to submit orders, allows factory-side apps
      to access orders by order number, allows factory-side apps to access
      the set of unseen orders directly, and allows a factory-side app
      to mark an order as seen.

      I envision having a top-level uri for the service which returns a
      document containing the uris needed to use the service. The uris would
      be something like

      <order-service-uris>
      <submit uri="/orders" />
      <get-order-by-number uri="/order-numbers" />
      <get-new-orders uri="/new-orders" />
      </order-service-uris>

      To submit an order, the client POSTs the order to /orders.

      To find an order by order number, the client does a GET on
      /order-numbers, which returns a page of metadata, like for instance:

      <orders>
      <ranges>
      <range begin="375" end="399" uri="/db/1201" />
      <range begin="400" end="424" uri="/db/14287" />
      </ranges>
      <singleton number="425" uri="/db/1798" />
      <singleton number="426" uri="/db/1855" />
      </orders>

      I see the singletons as necessary because a partial range uri must be
      kept forever in case someone cached it, yuck. This way, when a range is
      complete, it is allocated a permanent uri; until then it is returned as
      a collection of singletons.

      To get the list of unseen orders, the client does a GET on
      /new-orders, which returns a page of metadata like the above except it's
      all singletons. The uris distributed through /order-numbers and
      /new-orders are different for any given order, and:

      To mark an order seen, the client does a DELETE on the uri acquired from
      /new-orders.

      Does this seem like a ReSTful interface? All nitpicking is welcome, I'm
      still trying to internalize Roy Fielding's dissertation and the comments
      I've read here over the last month or so.

      Regards,

      Gary Shea
      shea@...
    • S. Mike Dierken
      ... From: Gary Shea This looks good overall. ... I m not clear on what the begin/end range means - could you explain? Is an individual
      Message 2 of 24 , Jan 9, 2003
      • 0 Attachment
        ----- Original Message -----
        From: "Gary Shea" <shea@...>

        This looks good overall.

        > To find an order by order number, the client does a GET on
        > /order-numbers, which returns a page of metadata, like for instance:
        >
        > <orders>
        > <ranges>
        > <range begin="375" end="399" uri="/db/1201" />
        > <range begin="400" end="424" uri="/db/14287" />
        > </ranges>
        > <singleton number="425" uri="/db/1798" />
        > <singleton number="426" uri="/db/1855" />
        > </orders>
        I'm not clear on what the begin/end range means - could you explain?
        Is an individual order addressable?

        >
        > I see the singletons as necessary because a partial range uri must be
        > kept forever in case someone cached it, yuck. This way, when a range is
        > complete, it is allocated a permanent uri; until then it is returned as
        > a collection of singletons.

        >
        > To mark an order seen, the client does a DELETE on the uri acquired from
        > /new-orders.
        I while ago there was some discussion about acknowledging messages or
        marking a resource as being processed in some way - there was a comparison
        between DELETE and POST with a body of 'status=seen'. I think the end result
        was that if there are multiple status values (ready, locked, finished, etc.)
        then you would POST the status (or PUT to a more detailed URI). If the
        existence of the resource is all the indication needed, then DELETE probably
        will work fine. Since you have two distinct URIs for 'new-orders' and
        'acknowledged orders' - deleting the one resource merely removes the
        relationship that the order is 'new' (or however you want to think of it)
        rather than deleting the order itself.
      • Gary Shea
        Hi -- Thanks for taking the time to comment. See inline... ... Sorry, I could have been more clear. An individual order is addressable. The idea was to find
        Message 3 of 24 , Jan 9, 2003
        • 0 Attachment
          Hi --

          Thanks for taking the time to comment. See inline...


          On Thu, 9 Jan 2003, at 09:48 [-0800], S. Mike Dierken (mdierken@......:

          >
          > ----- Original Message -----
          > From: "Gary Shea" <shea@...>
          >
          > This looks good overall.


          >
          > > To find an order by order number, the client does a GET on
          > > /order-numbers, which returns a page of metadata, like for instance:
          > >
          > > <orders>
          > > <ranges>
          > > <range begin="375" end="399" uri="/db/1201" />
          > > <range begin="400" end="424" uri="/db/14287" />
          > > </ranges>
          > > <singleton number="425" uri="/db/1798" />
          > > <singleton number="426" uri="/db/1855" />
          > > </orders>
          > I'm not clear on what the begin/end range means - could you explain?
          > Is an individual order addressable?

          Sorry, I could have been more clear.

          An individual order is addressable. The idea was to find an individual
          order by traversing an n-ary tree of uris. Inner nodes of the tree map
          a range of order numbers to a child node of the tree. The desired
          order's uri would be found in a leaf of the tree.

          I took this (baroque?) approach because the uri /order/by-number/2275 is
          so not opaque! It felt more ReSTful to act like a browser and follow
          a chain of links to get where I needed to go. The performance cost is
          not likely to be significant, given the predicted order load. Plus,
          if the process that traverses the tree has any kind of lifetime, it can
          cache everything, as none of the links change.

          Too weird?

          >
          > >
          > > I see the singletons as necessary because a partial range uri must be
          > > kept forever in case someone cached it, yuck. This way, when a range is
          > > complete, it is allocated a permanent uri; until then it is returned as
          > > a collection of singletons.
          >
          > >
          > > To mark an order seen, the client does a DELETE on the uri acquired from
          > > /new-orders.
          > I while ago there was some discussion about acknowledging messages or
          > marking a resource as being processed in some way - there was a comparison
          > between DELETE and POST with a body of 'status=seen'. I think the end result
          > was that if there are multiple status values (ready, locked, finished, etc.)
          > then you would POST the status (or PUT to a more detailed URI). If the
          > existence of the resource is all the indication needed, then DELETE probably
          > will work fine. Since you have two distinct URIs for 'new-orders' and
          > 'acknowledged orders' - deleting the one resource merely removes the
          > relationship that the order is 'new' (or however you want to think of it)
          > rather than deleting the order itself.

          That makes sense. One of the next steps will be associating a status
          with each order so this is very relevant! Using POST as you describe
          sounds like the way to go for updating the order status. If I think of
          NOT_SEEN as the initial status, I could use the POST as you describe to
          set the status to SEEN. So if the order is located at /order/2345,
          I could post to /order/2345/status, for instance.

          Regards,

          Gary Shea
          shea@...
        • Seairth Jacobs
          one clarification below... ... From: Gary Shea ... Your choice to use one URI over another doesn t indicate whether the URI is opaque or
          Message 4 of 24 , Jan 9, 2003
          • 0 Attachment
            one clarification below...

            ----- Original Message -----
            From: "Gary Shea" <shea@...>
            >
            > I took this (baroque?) approach because the uri /order/by-number/2275 is
            > so not opaque!

            Your choice to use one URI over another doesn't indicate whether the URI is
            opaque or not. It's a matter of whether the client attempts to treat it as
            anything more than an identifier or not that determines whether it's opaque.
            A RESTful client treats *all* URIs as opaque (though there has been some
            blurring of that stance lately, it seems).

            I think the common confusion about opacity is whether it's perceived as
            "human understandable" or not. The path you give could certainly be
            interpreted by a human beyond "it's an identifier", even though it
            shouldn't. Suppose instead that you were to have used the path /19394BC3EA.
            At first blush, one might say this URI is "more opaque". However, it is no
            more opaque than your example above if the client knows attempts to
            interpret it (e.g. knows the encoding scheme you use) beyond "it's an
            identifier". It is certainly less "human understandable", but that doesn't
            necessarily make it more opaque.

            If security is an issue, then remember that using /19394BC3EA instead of
            /order/by-number/2275 is only "security by obscurity", which not the way to
            go. So... why give up a particular format that makes development easier?
            You don't gain anything by it, IMHO.

            ---
            Seairth Jacobs
            seairth@...
          • S. Mike Dierken
            ... From: Gary Shea ... Not weird. Sounds very hypertextual. I m not sold on that being the best approach though. My reasoning is that
            Message 5 of 24 , Jan 9, 2003
            • 0 Attachment
              ----- Original Message -----
              From: "Gary Shea" <shea@...>

              > An individual order is addressable. The idea was to find an individual
              > order by traversing an n-ary tree of uris. Inner nodes of the tree map
              > a range of order numbers to a child node of the tree. The desired
              > order's uri would be found in a leaf of the tree.
              >
              > I took this (baroque?) approach because the uri /order/by-number/2275 is
              > so not opaque! It felt more ReSTful to act like a browser and follow
              > a chain of links to get where I needed to go. The performance cost is
              > not likely to be significant, given the predicted order load. Plus,
              > if the process that traverses the tree has any kind of lifetime, it can
              > cache everything, as none of the links change.
              >
              > Too weird?

              Not weird. Sounds very hypertextual. I'm not sold on that being the best
              approach though.
              My reasoning is that the client needs to know the document format and
              meaning - particular element names and the fact that they are relative
              references to more data that needs retrieval. Requiring that the client know
              the URI format and meaning - particular path segments or query terms - seems
              very similar to being coupled to document format.
              The client and server both share knowledge of a value space - the actual
              order number. This shared knowledge is required in both scenarios - you need
              to know what order number to look for in the list of leaf nodes for example.
              If knowledge of particular order numbers did not exist then finding a
              particular order is not possible.
              Describing that the server accepts order numbers in a portion of a URI as
              opposed to describing that the server reports the order numbers in a portion
              of XML content isn't much different to me.
              Perhaps I'm just biased to using URI query terms to do lookup because it is
              simple to code and easy to understand.


              > That makes sense. One of the next steps will be associating a status
              > with each order so this is very relevant! Using POST as you describe
              > sounds like the way to go for updating the order status. If I think of
              > NOT_SEEN as the initial status, I could use the POST as you describe to
              > set the status to SEEN. So if the order is located at /order/2345,
              > I could post to /order/2345/status, for instance.
              You could POST to /order/2345 directly - POST can be used for partial update
              of a resource. If you have a resource which represents the status directly,
              you could PUT to that instead (but I have problems with the defined behavior
              of PUT).
            • Gary Shea
              ... I completely agree with your points about opacity of URIs. I don t think they are relevant to this case though. The question is, how do I get access to a
              Message 6 of 24 , Jan 10, 2003
              • 0 Attachment
                On Thu, 9 Jan 2003, at 13:57 [-0500], Seairth Jacobs (seairth@...)...:

                > one clarification below...
                >
                > ----- Original Message -----
                > From: "Gary Shea" <shea@...>
                > >
                > > I took this (baroque?) approach because the uri /order/by-number/2275 is
                > > so not opaque!
                >
                > Your choice to use one URI over another doesn't indicate whether the URI is
                > opaque or not. It's a matter of whether the client attempts to treat it as
                > anything more than an identifier or not that determines whether it's opaque.
                > A RESTful client treats *all* URIs as opaque (though there has been some
                > blurring of that stance lately, it seems).
                >
                > I think the common confusion about opacity is whether it's perceived as
                > "human understandable" or not. The path you give could certainly be
                > interpreted by a human beyond "it's an identifier", even though it
                > shouldn't. Suppose instead that you were to have used the path /19394BC3EA.
                > At first blush, one might say this URI is "more opaque". However, it is no
                > more opaque than your example above if the client knows attempts to
                > interpret it (e.g. knows the encoding scheme you use) beyond "it's an
                > identifier". It is certainly less "human understandable", but that doesn't
                > necessarily make it more opaque.

                I completely agree with your points about opacity of URIs. I don't
                think they are relevant to this case though.

                The question is, how do I get access to a specific order document, given
                the order number.

                My original proposal was to do a tree search in a heirarchy of index
                pages, where the order number guides the search. In some index leaf
                page a pointer to the actual URI would be found. There would be no way
                to interpret the URI structure, because it doesn't have any: the
                mapping from order numbers to URIs is basically random. Completely
                opaque.

                The alternative approach suggested by S. Mike Dierken was to put
                the order number in the uri. Easy to interpret, totally not opaque.
                The client must know the significance of the final URI component in
                order to use the service.

                So, which method is more ReSTful? To me the first one is ReSTful, the
                second one isn't, but Mike obviously has been thinking about ReST longer
                than I have... so I accept that I'm probably missing something.

                My sense is that if the goal is: "Given a set of parameters, find the
                corresponding URI", there is only one ReSTful alternative, namely the
                inefficient search method described above. A solution that involves
                putting search information in a document and getting back a URI is
                RPC like (the intention is not described by the choice of
                PUT/POST/blah), and a solution that puts the search criteria in the URL
                requires that the structure of the URL be well-defined and so violates
                opaqueness. Eeek!

                Regards,

                Gary
              • S. Mike Dierken
                ... From: Gary Shea ... Not actually completely opaque. The client needs to know the format and structure of two documents. Either
                Message 7 of 24 , Jan 10, 2003
                • 0 Attachment
                  ----- Original Message -----
                  From: "Gary Shea" <shea@...>

                  > The question is, how do I get access to a specific order document, given
                  > the order number.

                  >
                  > My original proposal was to do a tree search in a heirarchy of index
                  > pages, where the order number guides the search. In some index leaf
                  > page a pointer to the actual URI would be found. There would be no way
                  > to interpret the URI structure, because it doesn't have any: the
                  > mapping from order numbers to URIs is basically random. Completely
                  > opaque.
                  Not actually completely opaque. The client needs to know the format and
                  structure of two documents. Either that's hardcoded - and hard things are
                  brittle - or the server describes the format (which gets you into a
                  recursive definition of how you describe information and find what you want
                  from that description).
                  If you go with the server description approach, then the server can just as
                  easily describe the format of the URI. If the server changes the structure,
                  the defintion changes - clients automatically adopt the new format.

                  > The alternative approach suggested by S. Mike Dierken was to put
                  > the order number in the uri. Easy to interpret, totally not opaque.
                  Add in a server description of how to construct the URI and you reduce the
                  coupling. I do realize that constructing URIs can be avoided in many
                  situations, but I think it adds implementation complexity for not a lot of
                  benefit. Just my opinion though.

                  > My sense is that if the goal is: "Given a set of parameters, find the
                  > corresponding URI", there is only one ReSTful alternative, namely the
                  > inefficient search method described above.
                  Well stated goal. And very good question - is there only one RESTful
                  approach?
                  I see two non-URI based approaches
                  a) successive GETs and matching against response content
                  b) POSTing some content with the parameter (the purchase order number) and
                  receiving the actual location

                  The URI-based approach might be simpler to implement, and a server-provided
                  description of the structure of the URI reduces coupling, but defining a URI
                  structure probably is going to limit the server to hosting the resources in
                  a simple container (like a database) otherwise the description gets too
                  complicated (although a re-direct would let you put things anywhere else
                  too). Using the non-URI based approaches lets you put the resources anywhere
                  on the Web.

                  So... for me, I'd do something simple when the job is simple and do
                  something large when the problem is large. Small steps toward automation are
                  better than no steps at all.
                • Seairth Jacobs
                  From: Gary Shea ... Some discussions I have seen in the past (sorry, don t remember where though probably on this list) had argued that
                  Message 8 of 24 , Jan 10, 2003
                  • 0 Attachment
                    From: "Gary Shea" <shea@...>
                    >
                    > The alternative approach suggested by S. Mike Dierken was to put
                    > the order number in the uri. Easy to interpret, totally not opaque.
                    > The client must know the significance of the final URI component in
                    > order to use the service.

                    Some discussions I have seen in the past (sorry, don't remember where though
                    probably on this list) had argued that if the server were telling the client
                    how to construct the URI, then the URI was still effectively opaque. In a
                    way, I agree with this, though I can't tell you why. It just "feels right"
                    somehow.

                    Anyone else remember this discussion?

                    ---
                    Seairth Jacobs
                    seairth@...
                  • Walden Mathews
                    Seairth, ... though ... client ... right ... I think it might have been spawned by Paul Prescod s First Principles paper. It feels right because if the
                    Message 9 of 24 , Jan 10, 2003
                    • 0 Attachment
                      Seairth,

                      > > The alternative approach suggested by S. Mike Dierken was to put
                      > > the order number in the uri. Easy to interpret, totally not opaque.
                      > > The client must know the significance of the final URI component in
                      > > order to use the service.
                      >
                      > Some discussions I have seen in the past (sorry, don't remember where
                      though
                      > probably on this list) had argued that if the server were telling the
                      client
                      > how to construct the URI, then the URI was still effectively opaque. In a
                      > way, I agree with this, though I can't tell you why. It just "feels
                      right"
                      > somehow.
                      >
                      > Anyone else remember this discussion?

                      I think it might have been spawned by Paul Prescod's "First Principles"
                      paper. It "feels right" because if the instructions are expressed in a
                      generic
                      language, then the client doesn't need the extra coupling to server-specific
                      protocol.

                      /walden
                    • Roy T. Fielding
                      ... Maybe I am missing something, but since several people have said that REST implies opaqueness in the URI, my guess is that a legend has somehow begun and I
                      Message 10 of 24 , Jan 10, 2003
                      • 0 Attachment
                        > So, which method is more ReSTful? To me the first one is ReSTful, the
                        > second one isn't, but Mike obviously has been thinking about ReST
                        > longer
                        > than I have... so I accept that I'm probably missing something.

                        Maybe I am missing something, but since several people have said that
                        REST implies opaqueness in the URI, my guess is that a legend
                        has somehow begun and I need to put it to rest (no pun intended).

                        REST does not require that a URI be opaque. The only place where
                        the word opaque occurs in my dissertation is where I complain about the
                        opaqueness of cookies. In fact, RESTful applications are, at all times,
                        encouraged to use human-meaningful, hierarchical identifiers in order
                        to maximize the serendipitous use of the information beyond what is
                        anticipated by the original application.

                        It is still necessary for the server to construct the URIs and for the
                        client to initially discover those URIs via hypertext responses, either
                        in the normal course of creating the resource or by some form of query
                        that results in a hypertext list. However, once that list is provided,
                        people can and do anticipate the names of other/future resources in
                        that name space, just as I would often directly type URIs into the
                        location bar rather than go through some poorly designed interactive
                        multi-page interface for stock charts.

                        Sites that rely on interstitial advertising (like the annoying yahoo
                        groups interface) do not like it when user's avoid the indirect path,
                        but the social network-effect of the Web is enhanced by meaningful URI.
                        In general, sites that give meaningful URI are used more often.

                        It also helps prevent the "lost in hyperspace" syndrome, but that's
                        a separate issue.


                        Cheers,

                        Roy T. Fielding, co-founder, The Apache Software Foundation
                        (fielding@...) <http://www.apache.org/>

                        Chief Scientist, Day Software
                        2 Corporate Plaza, Suite 150
                        Newport Beach, CA 92660-7929 fax:+1.949.644.5064
                        (roy.fielding@...) <http://www.day.com/>
                      • Jeff Bone
                        ... AAAAAAAAAARRRRRRRGGGGGGGHHHHHHHH! ... MOMENT OF TOTAL, VIOLENT, ZEN CLARITY!!! AGAIN!!! THANK YOU, ROY! ... jb
                        Message 11 of 24 , Jan 10, 2003
                        • 0 Attachment
                          On Friday, Jan 10, 2003, at 18:37 US/Central, Roy T. Fielding wrote:

                          > REST does not require that a URI be opaque.

                          AAAAAAAAAARRRRRRRGGGGGGGHHHHHHHH!

                          :brain melts.

                          MOMENT OF TOTAL, VIOLENT, ZEN CLARITY!!!

                          AGAIN!!!

                          THANK YOU, ROY!

                          :-)

                          jb
                        • Mark Baker
                          Yah, I thought long and hard about this recently due to Jon Udell s ISBN-in-the-URI javascript hack. There s no denying the value in that. I figure it s one
                          Message 12 of 24 , Jan 10, 2003
                          • 0 Attachment
                            Yah, I thought long and hard about this recently due to Jon Udell's
                            ISBN-in-the-URI javascript hack. There's no denying the value in that.

                            I figure it's one of those things with an upside and a downside. The
                            upside is the serendipity. The downside is serendipity. 8-) What I
                            mean is that as a consumer of a URI, it's awesome to be able to get
                            more info and use it in unexpected ways. But on the other hand, for
                            the URI publisher, you can't know what information people or software
                            may be extracting from your URI, and that ties your hands somewhat with
                            respect to how your URI space can evolve.

                            I used to think the problems with the latter outweighed the benefits
                            of the former, but I think it's the other way around now after seeing
                            it in action. At least the publisher has the option of obfuscating
                            their URIs if they don't want to have to worry about it.

                            BTW, the RESTwiki's down due to a machine swap. I'll have to fix it
                            this weekend.

                            MB
                            --
                            Mark Baker. Ottawa, Ontario, CANADA. http://www.markbaker.ca
                            Web architecture consulting, technical reports, evaluation & analysis
                          • Miles Sabin
                            Roy T. Fielding wrote, ... Interesting. I think you re saying that it s legitimate from a REST POV for a client to infer a URI pattern or template, eg.
                            Message 13 of 24 , Jan 11, 2003
                            • 0 Attachment
                              Roy T. Fielding wrote,
                              > REST does not require that a URI be opaque.

                              Interesting.

                              I think you're saying that it's legitimate from a REST POV for a client
                              to infer a URI pattern or template, eg.

                              http://example.invalid/foo?foo=$1

                              or,

                              http://example.invalid/foo/$1

                              where the client can substitute into the $1 position to obtain a URI and
                              have some reasonable expectation that the server manages a
                              corresponding resource.

                              These URI templates aren't URIs, clearly. They represent a family of
                              related URIs: an infinite family if arbitrary substitutions into the
                              template positions are acceptable; a finite family if the substutions
                              should be drawn from a restricted set as in an HTML <select>.

                              But they do seem like identifiers for all that, even if only virtual/
                              derived and parasitic on the "true" identifiers which support them.
                              What would support a clients expectation that substutions into,

                              http://example.invalid/foo?foo=$1

                              would be likely to generate dereferencable URIs other than an assumption
                              that the URI template effectively identifies a _process_ (or something
                              equivalent) which is able to perform the inverse operation on the URI
                              and extract the substitued-in value as a parameter for a computation?

                              I wonder if something like the above would go some way towards tweaking
                              RFC 2396 3.4 in a REST-consistent direction?

                              Cheers,


                              Miles
                            • Roy T. Fielding
                              ... Reasonable expectation? Hmmm. All links are wishful thinking. Guessed links are just somewhat more wishful than others. ... Er, don t think too hard
                              Message 14 of 24 , Jan 11, 2003
                              • 0 Attachment
                                > I think you're saying that it's legitimate from a REST POV for a client
                                > to infer a URI pattern or template, eg.
                                >
                                > http://example.invalid/foo?foo=$1
                                >
                                > or,
                                >
                                > http://example.invalid/foo/$1
                                >
                                > where the client can substitute into the $1 position to obtain a URI
                                > and
                                > have some reasonable expectation that the server manages a
                                > corresponding resource.

                                Reasonable expectation? Hmmm. All links are wishful thinking.
                                Guessed links are just somewhat more wishful than others.

                                > These URI templates aren't URIs, clearly. They represent a family of
                                > related URIs: an infinite family if arbitrary substitutions into the
                                > template positions are acceptable; a finite family if the substutions
                                > should be drawn from a restricted set as in an HTML <select>.

                                Er, don't think too hard about it. All URIs are URIs -- some resources
                                just don't (currently) have a representation.

                                > But they do seem like identifiers for all that, even if only virtual/
                                > derived and parasitic on the "true" identifiers which support them.
                                > What would support a clients expectation that substutions into,
                                >
                                > http://example.invalid/foo?foo=$1
                                >
                                > would be likely to generate dereferencable URIs other than an
                                > assumption
                                > that the URI template effectively identifies a _process_ (or something
                                > equivalent) which is able to perform the inverse operation on the URI
                                > and extract the substitued-in value as a parameter for a computation?

                                A hierarchical namespace typically assigns semantics to each name in
                                the hierarchy, and a well-written server-side application will
                                respond consistently to requests throughout that namespace, keeping
                                in mind that "not found" is a consistent response if, in fact, there
                                is no associated representation for that name. It is often harder
                                to interpret the same of query info because it is unordered, which
                                is why developers should not hide hierarchy inside queries.

                                > I wonder if something like the above would go some way towards tweaking
                                > RFC 2396 3.4 in a REST-consistent direction?

                                It is difficult to write good descriptions for URI components given
                                that schemes frequently differ in some uses. The descriptions in
                                RFC 2396 give the intent, even though they can be misused in practice.
                                I suspect that most of the spec will have to be rewritten before all
                                of the authors will agree, let alone the IETF reviewers.

                                ....Roy
                              • Miles Sabin
                                Roy T. Fielding wrote, ... Well, yeah. I meant reasonable in the sense of not completely ridiculous . It s surely more reasonable for a client to expect
                                Message 15 of 24 , Jan 11, 2003
                                • 0 Attachment
                                  Roy T. Fielding wrote,
                                  > > I think you're saying that it's legitimate from a REST POV for a
                                  > > client to infer a URI pattern or template, eg.
                                  > >
                                  > > http://example.invalid/foo?foo=$1
                                  > >
                                  > > or,
                                  > >
                                  > > http://example.invalid/foo/$1
                                  > >
                                  > > where the client can substitute into the $1 position to obtain a
                                  > > URI and have some reasonable expectation that the server manages a
                                  > > corresponding resource.
                                  >
                                  > Reasonable expectation? Hmmm. All links are wishful thinking.
                                  > Guessed links are just somewhat more wishful than others.

                                  Well, yeah.

                                  I meant "reasonable" in the sense of "not completely ridiculous". It's
                                  surely more reasonable for a client to expect that if it which receives
                                  an HTML form with a GET action of,

                                  http://example.invalid/foo

                                  and a control name of "foo" that,

                                  http://example.invalid/foo?foo=wibble

                                  will identify a resource with a representation than it would be for it
                                  to expect that,

                                  http://example.invalid/foo/3lk4j5l3jkd84oikl

                                  will (where the last path element it a client genarated random string).

                                  > > These URI templates aren't URIs, clearly. They represent a family
                                  > > of related URIs: an infinite family if arbitrary substitutions into
                                  > > the template positions are acceptable; a finite family if the
                                  > > substutions should be drawn from a restricted set as in an HTML
                                  > > <select>.
                                  >
                                  > Er, don't think too hard about it. All URIs are URIs -- some
                                  > resources just don't (currently) have a representation.

                                  Right, but a URI _template_ isn't a URI. It's a pattern a client might
                                  instantiate to create a URI in the hope that that URI identifies a
                                  resource with a representation.

                                  > > But they do seem like identifiers for all that, even if only
                                  > > virtual/ derived and parasitic on the "true" identifiers which
                                  > > support them. What would support a clients expectation that
                                  > > substutions into,
                                  > >
                                  > > http://example.invalid/foo?foo=$1
                                  > >
                                  > > would be likely to generate dereferencable URIs other than an
                                  > > assumption that the URI template effectively identifies a _process_
                                  > > (or something equivalent) which is able to perform the inverse
                                  > > operation on the URI and extract the substitued-in value as a
                                  > > parameter for a computation?
                                  >
                                  > A hierarchical namespace typically assigns semantics to each name in
                                  > the hierarchy, and a well-written server-side application will
                                  > respond consistently to requests throughout that namespace, keeping
                                  > in mind that "not found" is a consistent response if, in fact, there
                                  > is no associated representation for that name. It is often harder
                                  > to interpret the same of query info because it is unordered, which
                                  > is why developers should not hide hierarchy inside queries.

                                  OK, I'd be happy to replace "process" with "hierarchical namespace".
                                  That'd give us something like: a URI template identifies (in a
                                  virtual/derivative/parasitic sense) a hierarchical namespace maintained
                                  by the server-side application.

                                  I think that's better than saying it identifies a process, if only
                                  because it's more general.

                                  > > I wonder if something like the above would go some way towards
                                  > > tweaking RFC 2396 3.4 in a REST-consistent direction?
                                  >
                                  > It is difficult to write good descriptions for URI components given
                                  > that schemes frequently differ in some uses. The descriptions in
                                  > RFC 2396 give the intent, even though they can be misused in
                                  > practice. I suspect that most of the spec will have to be rewritten
                                  > before all of the authors will agree, let alone the IETF reviewers.

                                  Agreed.

                                  But 3.4 is scheme neutral now, and it might be possible to replace it
                                  with something more REST-consistent without losing that neutrality.
                                  Perhaps instead of,

                                  The query component is a string of information to be interpreted by
                                  the resource.

                                  we could have something like,

                                  The presence of a query component suggests the existence of a
                                  family of resources with representations whose URIs vary in a
                                  well-defined but scheme-specific and server-dependent way.
                                  Applications which are aware the constraints of the scheme and the
                                  capabilities of the server MAY vary the query component in the
                                  expectation that the resulting URIs identify a resource with a
                                  representation.

                                  Thoughts?

                                  Cheers,


                                  Miles
                                • Bill de hÓra
                                  ... FTR, it s an axiom of web architecture according to TBL s notes, ie a self-evident truth. ... Jon Udell [1] has come up with extracting ISBNs from amazon
                                  Message 16 of 24 , Jan 11, 2003
                                  • 0 Attachment
                                    Miles Sabin wrote:
                                    > Roy T. Fielding wrote,
                                    >
                                    >>REST does not require that a URI be opaque.
                                    >

                                    FTR, it's an axiom of web architecture according to TBL's notes, ie
                                    a self-evident truth.


                                    > Interesting.
                                    >
                                    > I think you're saying that it's legitimate from a REST POV for a client
                                    > to infer a URI pattern or template, eg.
                                    >
                                    > http://example.invalid/foo?foo=$1
                                    >
                                    > or,
                                    >
                                    > http://example.invalid/foo/$1

                                    Jon Udell [1] has come up with extracting ISBNs from amazon links
                                    and using them in other sites' query strings. He's recieved near
                                    universal acclaim for doing so. If you buy into TBL's strong claim
                                    (URI opacity is an axiom), or Paul Prescod's weaker variant (peeking
                                    into URIs is a bad idea), then what Jon's done is a nasty hack (a la
                                    screenscraping), and not has popular opinion has it, a neat hack.
                                    Either way, this hack seems to offer considerable, immediate, utility.

                                    Maybe this an issue that needs to be punted onto the TAG. It seems
                                    the web has a constaint over and above any of REST's (is that a first?).

                                    Bill de hÓra

                                    [1]
                                    http://weblog.infoworld.com/udell/stories/2002/12/11/librarylookup.html
                                  • Seairth Jacobs
                                    From: Bill de hÓra ... The problem here is not that Jon extracted information out of the URI. The problem is that Jon is relying on
                                    Message 17 of 24 , Jan 11, 2003
                                    • 0 Attachment
                                      From: "Bill de hÓra" <dehora@...>
                                      >
                                      > Jon Udell [1] has come up with extracting ISBNs from amazon links
                                      > and using them in other sites' query strings. He's recieved near
                                      > universal acclaim for doing so. If you buy into TBL's strong claim
                                      > (URI opacity is an axiom), or Paul Prescod's weaker variant (peeking
                                      > into URIs is a bad idea), then what Jon's done is a nasty hack (a la
                                      > screenscraping), and not has popular opinion has it, a neat hack.
                                      > Either way, this hack seems to offer considerable, immediate, utility.
                                      >
                                      > Maybe this an issue that needs to be punted onto the TAG. It seems
                                      > the web has a constaint over and above any of REST's (is that a first?).

                                      The problem here is not that Jon extracted information out of the URI. The
                                      problem is that Jon is relying on Amazon to not change it's URIs in a way
                                      that will break his technique. Had Amazon said "one can extract ISBNs from
                                      our URIs thus", then no one would be saying that what Jon did was a hack.
                                      This all goes back to the/my thought that as long as the server (or server's
                                      authority) dictates how a given URI is composed, then it should be perfectly
                                      fine to extract information out of the URI.

                                      As to whether the URI (or class of URIs) is opaque, I still think that they
                                      are. As long as the client conforms to the composition rule(s) given by the
                                      server (the simplest case being a URI whose only rule is "this is the URI"),
                                      then I don't see how those constructed URIs would be any different than if
                                      the server returned all possible combinations that matched the given
                                      composition rule(s). Either way, they would still be "opaque". It's only
                                      when the client attempts to go outside of the composition rules that we get
                                      in trouble.

                                      Back to Jon's example above, Amazon has implictly told us (as most sites
                                      implicitly do) that the only rule for their URIs is "this is the URI"
                                      (ignoring any generated via a form or javascript). Jon went outside of the
                                      rules that Amazon provided, thus he is violating the opacity that TimBL
                                      talks about.

                                      IMHO, of course.... :)

                                      ---
                                      Seairth Jacobs
                                      seairth@...
                                    • Bill de hÓra
                                      ... Yep. Low cohesion, high coupling. But it works for now. Bill de hÓra
                                      Message 18 of 24 , Jan 11, 2003
                                      • 0 Attachment
                                        Seairth Jacobs wrote:

                                        > The problem here is not that Jon extracted information out of the URI. The
                                        > problem is that Jon is relying on Amazon to not change it's URIs in a way
                                        > that will break his technique. Had Amazon said "one can extract ISBNs from
                                        > our URIs thus", then no one would be saying that what Jon did was a hack.
                                        > This all goes back to the/my thought that as long as the server (or server's
                                        > authority) dictates how a given URI is composed, then it should be perfectly
                                        > fine to extract information out of the URI.

                                        Yep. Low cohesion, high coupling. But it works for now.

                                        Bill de hÓra
                                      • Seairth Jacobs
                                        Out of curiousity, are there any spec (or what have you) out that that adress this? Specifically, I am talking about the ability for a URI authority to
                                        Message 19 of 24 , Jan 11, 2003
                                        • 0 Attachment
                                          Out of curiousity, are there any spec (or what have you) out that that
                                          adress this? Specifically, I am talking about the ability for a URI
                                          authority to indicate in a computer-readable format the composition rules of
                                          a given URI? For instance, suppose there was a document that looked
                                          something like (loosely based on regex):

                                          https?://example.invalid/(isbn)
                                          isbn = {regex pattern for ISBNs}

                                          This would have two uses:

                                          1) Allows the client to infer structure and create "valid" URIs that were
                                          not explicitly given to them by the server.
                                          2) Be able to extract information out or URIs that are explicitly given to
                                          them by the server (obviously with a bit of human help).

                                          If Jon had been given something like the above, he could have just told his
                                          program to find the part that matches "isbn". If Amazon chose to change the
                                          (preferably, add a new) URI pattern to something like:

                                          https?::/example.invalid/somepath/(isbn)/(nuflag)
                                          isbn = {regex pattern for ISBNs}
                                          nuflag = "new" | "used"

                                          Jon's program would keep working because it still new where to find the
                                          appropriate information. This would allow looser coupling and high
                                          cohesion. Just a thought....

                                          ---
                                          Seairth Jacobs
                                          seairth@...


                                          From: "Bill de hÓra" <dehora@...>
                                          >
                                          > Seairth Jacobs wrote:
                                          >
                                          > > The problem here is not that Jon extracted information out of the URI.
                                          The
                                          > > problem is that Jon is relying on Amazon to not change it's URIs in a
                                          way
                                          > > that will break his technique. Had Amazon said "one can extract ISBNs
                                          from
                                          > > our URIs thus", then no one would be saying that what Jon did was a
                                          hack.
                                          > > This all goes back to the/my thought that as long as the server (or
                                          server's
                                          > > authority) dictates how a given URI is composed, then it should be
                                          perfectly
                                          > > fine to extract information out of the URI.
                                          >
                                          > Yep. Low cohesion, high coupling. But it works for now.
                                          >
                                          > Bill de hÓra
                                          >
                                          >
                                          >
                                          > To unsubscribe from this group, send an email to:
                                          > rest-discuss-unsubscribe@yahoogroups.com
                                          >
                                          >
                                          >
                                          > Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
                                          >
                                          >
                                          >
                                        • Bill de hÓra
                                          ... I don t think there is, but there should be; it would be useful. The biggest problem would be trying to avoid inventing URI Markup Language instead of a
                                          Message 20 of 24 , Jan 11, 2003
                                          • 0 Attachment
                                            Seairth Jacobs wrote:
                                            > Out of curiousity, are there any spec (or what have you) out that that
                                            > adress this? Specifically, I am talking about the ability for a URI
                                            > authority to indicate in a computer-readable format the composition rules of
                                            > a given URI? For instance, suppose there was a document that looked
                                            > something like (loosely based on regex):
                                            > [...]
                                            > Jon's program would keep working because it still new where to find the
                                            > appropriate information. This would allow looser coupling and high
                                            > cohesion. Just a thought....

                                            I don't think there is, but there should be; it would be useful. The
                                            biggest problem would be trying to avoid inventing URI Markup
                                            Language instead of a tidy notation like XPath, or some invariants
                                            applied to a regex as you did.

                                            Bill de hÓra
                                          • inthedarkplace <inthedarkplace@yahoo.com>
                                            ... that ... rules of ... Personally, I think is an absolutely terrible idea and leads to interfaces just as brittle as an RPC system. The best way to
                                            Message 21 of 24 , Jan 11, 2003
                                            • 0 Attachment
                                              --- In rest-discuss@yahoogroups.com, "Seairth Jacobs" <seairth@s...>
                                              wrote:
                                              > Out of curiousity, are there any spec (or what have you) out that
                                              that
                                              > adress this? Specifically, I am talking about the ability for a URI
                                              > authority to indicate in a computer-readable format the composition
                                              rules of
                                              > a given URI? For instance, suppose there was a document that looked
                                              > something like (loosely based on regex):
                                              >
                                              > https?://example.invalid/(isbn)
                                              > isbn = {regex pattern for ISBNs}

                                              Personally, I think is an absolutely terrible idea and leads to
                                              interfaces just as brittle as an RPC system. The best way to
                                              implement this functionality, (at least the way I do it) is to use a
                                              redirecting query ie

                                              GET /example.com/somepath/?isbn={isbn}&nuflag={nuflag}

                                              This should return a 302 Redirect who's location header is then the
                                              real URL, http://example.com/somepath/{isbn}/{nuflag}.

                                              Using redirecting queries is a lot more flexible then 'parameterized'
                                              URLs since it keeps the full URL-resoultion strategy on the server
                                              where it belongs. Also, queries are logical constructs which do not
                                              change while URLs can change at any time (under heavy load, some
                                              webservices will migrate resources to another machine). This also
                                              allows people to throw together quick scripting hacks like Udell's.

                                              (I would hardly call John's lookup anything other than a hack. It'll
                                              break as soon as Amazon changes its URLs, something he has no control
                                              over).

                                              Unfortunately, I really have to disagree Roy on this. There's
                                              absolutely nothing with human readable resources--in fact they should
                                              be encouraged--but URI opaqueness is fundamental and very important
                                              to building flexible systems. The only thing a client should be doing
                                              to a URL is applying the basic verbs (GET,PUT,POST,etc) to it. It's
                                              just a locator. Machines aren't as smart as humans.

                                              - Buko O.
                                            • S. Mike Dierken
                                              ... From: Seairth Jacobs ... of ... Like this: -- document from http://library.example.foo/lookupService/ --
                                              Message 22 of 24 , Jan 11, 2003
                                              • 0 Attachment
                                                ----- Original Message -----
                                                From: "Seairth Jacobs" <seairth@...>

                                                > Specifically, I am talking about the ability for a URI
                                                > authority to indicate in a computer-readable format the composition rules
                                                of
                                                > a given URI?

                                                Like this:

                                                -- document from http://library.example.foo/lookupService/ --
                                                <form method='GET' action='books'>
                                                <input name='isbn'>
                                                </form>

                                                This results in the URI pattern of:
                                                http://library.example.foo/lookupService/books/?isbn=$value$


                                                The problem is that nobody knows what 'isbn' means. If we add an attribute
                                                like 'class' or 'type', then Google will be able to tell us all the URI
                                                patterns that support injecting values of a certain type - like ISBN
                                                numbers. Or automobile VINs. Or UPC codes. Or telephone numbers. Or email
                                                addresses. etc.

                                                For example:
                                                <form method='GET' action='books'>
                                                <input name='isbn' class='industry-acceptable-identifier-for-ISBN-concept'>
                                                </form>

                                                Of course, I'd like to have a more rich language that specifies not just a
                                                URI, but a full HTTP request - the method, request-uri, headers, content,
                                                etc. Maybe if we added another attribute on <input> as to what the target
                                                is - where to inject the value - then a client could programmatically
                                                generate the appropriate request.
                                              • S. Mike Dierken
                                                ... From: Mark Baker ... There are two aspects to what Jon Udell did that make it work - parsing a URI and having two services share a
                                                Message 23 of 24 , Jan 11, 2003
                                                • 0 Attachment
                                                  ----- Original Message -----
                                                  From: "Mark Baker" <distobj@...>

                                                  > Yah, I thought long and hard about this recently due to Jon Udell's
                                                  > ISBN-in-the-URI javascript hack. There's no denying the value in that.

                                                  There are two aspects to what Jon Udell did that make it work - parsing a
                                                  URI and having two services share a common value space.
                                                  The sharing a common value space part hasn't been discussed much, but I
                                                  think it is an important piece of building network based applications across
                                                  organizational boundaries.

                                                  In my experience, developers tend to expose internal keys of whatever
                                                  database they are using for their application. This is because it makes
                                                  sense for the local application and is fast. If you have a URI of
                                                  http://localhost/viewstory.jsp?storyId=777 then parsing integers and using
                                                  integers for primary keys is fast and keeps the db tables small.
                                                  But if you have another 'key' that could possibly be used - like SSN, ISBN,
                                                  zip code, etc. - this would help integrate with other systems that also use
                                                  or understand those types of values. Storing long textual values as a
                                                  primary key might be a practice avoided by db designers, but when looking at
                                                  the larger scope of the system (outside a single server or department) it
                                                  might bring more benefits. There also might be implementation tricks that
                                                  minimize the performance and storage problems of large primary keys.

                                                  These are just some rough thoughts I've had for a while & the Library Lookup
                                                  bookmarklet makes a great discussion point.
                                                • Joe Gregorio
                                                  ... I think you have to be clear about the context before talking about opaqueness. Are you constructing a URI or deconstructing a URI? If you are
                                                  Message 24 of 24 , Jan 11, 2003
                                                  • 0 Attachment
                                                    inthedarkplace wrote:

                                                    > Unfortunately, I really have to disagree Roy on this. There's
                                                    > absolutely nothing with human readable resources--in fact they should
                                                    > be encouraged--but URI opaqueness is fundamental and very important
                                                    > to building flexible systems. The only thing a client should be doing
                                                    > to a URL is applying the basic verbs (GET,PUT,POST,etc) to it. It's
                                                    > just a locator. Machines aren't as smart as humans.
                                                    >

                                                    I think you have to be clear about the context before talking about
                                                    opaqueness. Are you 'constructing' a URI or 'deconstructing' a URI?
                                                    If you are deconstructing a URI, like Jon is doing in his ISBN app
                                                    then it is fragile and I agree that the URI should be handled
                                                    opaquely.

                                                    On the other hand if you are constructing a URI I believe it is
                                                    fine to do so. For example search engines do this all the time
                                                    when they look for your 'robots.txt' file. Your browser also does it
                                                    when it looks for 'favicon.ico'.

                                                    -joe

                                                    --
                                                    http://BitWorking.org
                                                    http://WellFormedWeb.org
                                                  Your message has been successfully submitted and would be delivered to recipients shortly.