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

Re: [rest-discuss] Correct REST principles

Expand Messages
  • Hugh Winkler
    ... It s probably best practice if everything before the ? identifies a service and the query string after the ? really is simply parameters to that
    Message 1 of 11 , Nov 30, 2005
    • 0 Attachment
      On 11/30/05, Christian Jensen <christianj@...> wrote:
      > Hi there,
      >
      > I am considering starting a new project that will end up being AJAX
      > enabled. I have XML-RPC, JSON and SOAP experience but want to give REST
      > a shot...
      >
      > I have 2 burning questions....
      >
      > 1. Is it considered bad taste to use parameters (i.e. ?id=1) within the
      > URL? From what I have read it is but everyone seems to be doing it.

      It's probably best practice if everything before the '?' identifies a
      service and the query string after the '?' really is simply parameters
      to that service. If the parameters really define a hierarchy you might
      consider making them part of the service URI e.g.
      /folders?name=pictures might be /folders/pictures. There's some
      advantage in that to whatever extent you can make your namespace
      hierarchical, you can use relative URIs. Also there used to be some
      caches that didn't handle query strings properly, and I don't know if
      that behavior has improved over the last couple years.

      > 2. What is considered the standard practice for user authentication? As
      > I understand it Sessions are supposed to be a thing of the past, but how
      > would I work around that? Standard HTTP authentication?
      >

      Right: sessions are bad. Use HTTP Basic authentication:
      http://www.ietf.org/rfc/rfc2617.txt


      > Thanks in advance!
      > Christian
      >
      >

      Hugh
    • Yannick Loiseau
      ... AFAIK, you can use JSON in a Rest-style service, since Rest only defines the architecture (i.e. communication, invocation ) of the service. The resource
      Message 2 of 11 , Dec 1, 2005
      • 0 Attachment
        > I have XML-RPC, JSON and SOAP experience but want to give REST
        > a shot...

        AFAIK, you can use JSON in a Rest-style service, since Rest only defines
        the architecture (i.e. communication, "invocation") of the service. The
        resource representations can be in any format, including Javascrip. Rest
        is not tied to Xml.
      • Costello, Roger L.
        ... the ... This is an excellent question, and has also been a question on my mind of late. My thinking is this: The sole purpose of a URL is to identify a
        Message 3 of 11 , Dec 1, 2005
        • 0 Attachment
          > 1. Is it considered bad taste to use parameters (i.e. ?id=1) within the
          > URL? From
          what I have read it is but everyone seems to be doing it.

          This is an excellent question, and has also been a question on my mind of late.
           
          My thinking is this: The sole purpose of a URL is to "identify" a resource. 
           
          Tim Berners-Lee Axiom 0: every resource on the Web shall be uniquely identified by a URL.
           
          For example, this (logical URL) identifies a 747 aircraft resource:
           
           
          If we agree that the sole purpose of a URL is to identify a resource, then I cannot see why a person would ever use query strings.  If information needs to be passed to the resource, then you must ask "why?"  Are you wishing to update a resource?  If so, then you should POST the information to the resource (and the resource is identified using a logical URL without any query strings).
           
          I am eager to hear what others are thinking on this topic.  /Roger
        • Christian Jensen
          After a good nights rest :) I have a slightly better thought set - no query strings. A query string seems to be a way to normalize a response, meaning: to take
          Message 4 of 11 , Dec 1, 2005
          • 0 Attachment
            After a good nights rest :) I have a slightly better thought set - no query strings.

            A query string seems to be a way to normalize a response, meaning: to take out the hierarchical ordering of the URL

            The following makes sense: http://[host]//[universe]/[galaxy]/[system]/[planet] but then what do you do with the latitude and longitude?

            It is a toss up:
            http://[host]///[universe]/[galaxy]/[system]/[planet]/[latitude]/[longitude]
            or
            http://[host]///[universe]/[galaxy]/[system]/[planet]/[longitude]/[latitude]

            Either works, but which one is correct? They are both equally ranked and are not at all hierarchical.

            Using a query string paradigm you would simple add ?latitude=90.0&longitude=12.0

            But I propose the following: http://[host]///[universe]/[galaxy]/[system]/[planet]/90.0%2012.0

            I am considering using a space (%20) because it is easily parsed. I am using latitude first because that is how we say it in natural language. So what happens if you need to do an actual query string - how would you RESTify Google search page? ../query/my%20search seems totally broken and really does not describe what the URL is... I will do more thinking on this - anyone have an answer?

            This brings up 2 additional points: what is this URLs type - I am an advocate of having the HTTP mime type specified as the data is retrieved (as opposed to the file extension dictating the mime). The second point is something that I have always had a pet peeve about - the trailing slash - a URL should never have a trailing slash. If there is a trailing slash, the inference is made by the web server - index.html, index.php, default.aspx - whatever - this in my opinion is faulty - a URL should say what it means and mean what it says. Am I among like believers?

            In my example, I never indicated with the URL exactly the classification of the service (with a /photos/ or a /heightmaps/ etc.). Personally, I feel that a URL should be self discovering, that is to says that if I were to trim down the URL down to just http://[host]///[universe]/[galaxy]/[system]/[planet] the data would be something that allows me to further progress, my initial proposition is to use RDF for this. So in this example, the RDF would shoot back a list of URLs that are under this one and describe them.

            Thoughts? Am I on the right path?

            Costello, Roger L. wrote:
            > 1. Is it considered bad taste to use parameters (i.e. ?id=1) within the
            > URL? From what I have read it is but everyone seems to be doing it.

            This is an excellent question, and has also been a question on my mind of late.
             
            My thinking is this: The sole purpose of a URL is to "identify" a resource. 
             
            Tim Berners-Lee Axiom 0: every resource on the Web shall be uniquely identified by a URL.
             
            For example, this (logical URL) identifies a 747 aircraft resource:
             
             
            If we agree that the sole purpose of a URL is to identify a resource, then I cannot see why a person would ever use query strings.  If information needs to be passed to the resource, then you must ask "why?"  Are you wishing to update a resource?  If so, then you should POST the information to the resource (and the resource is identified using a logical URL without any query strings).
             
            I am eager to hear what others are thinking on this topic.  /Roger
          • Mike Dierken
            There s been a lot of discussion on this point & my opinion is that the full URI is inclusive of the query terms. The query terms are actually part of
            Message 5 of 11 , Dec 1, 2005
            • 0 Attachment
              There's been a lot of discussion on this point & my opinion is that the full URI is inclusive of the query terms. The query terms are actually part of identifying the resource (I also believe the specification indicates this as well - http://www.gbiv.com/protocols/uri/rfc/rfc3986.html). The text string can be considered opaque by a lot of software applications, and other applications pull data out of portions of the URI regardless of where in that text string it is - path segments, segment parameters or query terms.
               


              From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On Behalf Of Costello, Roger L.
              Sent: Thursday, December 01, 2005 7:42 AM
              To: rest-discuss@yahoogroups.com
              Subject: Re: [rest-discuss] Correct REST principles

              > 1. Is it considered bad taste to use parameters (i.e. ?id=1) within the
              > URL? From what I have read it is but everyone seems to be doing it.

              This is an excellent question, and has also been a question on my mind of late.
               
              My thinking is this: The sole purpose of a URL is to "identify" a resource. 
               
              Tim Berners-Lee Axiom 0: every resource on the Web shall be uniquely identified by a URL.
               
              For example, this (logical URL) identifies a 747 aircraft resource:
               
               
              If we agree that the sole purpose of a URL is to identify a resource, then I cannot see why a person would ever use query strings.  If information needs to be passed to the resource, then you must ask "why?"  Are you wishing to update a resource?  If so, then you should POST the information to the resource (and the resource is identified using a logical URL without any query strings).
               
              I am eager to hear what others are thinking on this topic.  /Roger
            • Donald_Strong@national.com.au
              Hi Roger and Christian, ... A query URL (ie. a URL that contains a query path) is useful in a web service for the same reason it is useful in HTML; It allows
              Message 6 of 11 , Dec 1, 2005
              • 0 Attachment
                Hi Roger and Christian,

                > If we agree that the sole purpose of a URL is to identify a resource,
                > then I cannot see why a person would ever use query strings.
                > If information needs to be passed to the resource, then you must
                > ask "why?" Are you wishing to update a resource? If so, then you
                > should POST the information to the resource (and the resource is
                > identified using a logical URL without any query strings).

                A query URL (ie. a URL that contains a query path) is useful in a
                web service for the same reason it is useful in HTML; It allows the
                User Agent to construct a URL according to a specification provided by
                the Origin Server. The User Agent can then GET the representation
                with a high expectation that the URL will be understood and accepted.

                I have likened this, in the past, to asking a question of the resource.
                This makes sense if the resource that provided the form (input
                specification)
                is the same one the form is submitted to, eg.

                GET http://acme.com/aircraft

                <form action="/aircraft">
                <input type="text" name="manufacturer"/>
                <input type="text" name="pax_capacity"/>
                </form>

                GET http://acme.com/aircraft?manufacturer=Boeing&pax_capacity=300


                > But I propose the following: http://[host
                ]///[universe]/[galaxy]/[system]/[planet]/90.0%2012.0

                I have also suggested using segment parameters in the past.

                http://acme.com/universe/milkyway/sol/earth/lat=90.0;long=12.0/30000

                This has the advantage that more segments can be used after the params.
                In this case I have specified a height or 30000 feet.

                Donald.
              • Christian Jensen
                First off - just for kicks I clicked the URL :) pretty funny. REST performed by JSON, HTTP Authentication tied to PHP - that is my target. JSON is clean and
                Message 7 of 11 , Dec 2, 2005
                • 0 Attachment
                  First off - just for kicks I clicked the URL :) pretty funny.

                  REST performed by JSON, HTTP Authentication tied to PHP - that is my target.

                  JSON is clean and lightweight as well as HTTP Authentication, the PHP
                  side of things is clean and moderately lightweight.

                  The part I am having a tiny struggle with is the representation of the
                  URI that is passed to PHP. The nodes between the slashes are to indicate
                  the hierachy and need to be easily parsed, in the same general feeling
                  that JSON is virtually a native parsing.

                  I would love to simply explode() the path, send the entire array down
                  into the top of a handler and any sub processing handle within,
                  returning a final datastream (RDF, JSON, XML etc.)

                  Such as this:

                  http://acme.com/universe/milkyway/sol/earth/lat=90.0;long=12.0/30000

                  becomes (sparing the quotes):

                  $exploded_array = [universe, milkyway, sol, earth, lat=90.0;long=12.0,
                  30000]

                  Instead of plucking out each value and sending off to a function, I am
                  thinking that I might do:

                  <?

                  require_once('inc.functions.php');

                  $exploded_array = $_SERVER['REQUEST_URI'];

                  $scheme = 'http://'; // normally build this from parse_url
                  $host = 'acme.com';
                  $base = Array();
                  $result = process($exploded_array, $scheme, $host, $base)

                  header('Content-Type: ' . $result['mime']);
                  print $result['data'];
                  ?>

                  The "process" function would simply take off the first item off the
                  array and pass the remaining to another function. If there were no other
                  array elements (it is the target of the URI), then it would go ahead and
                  return the appropriate mime type and data to be sent back to the requester.

                  function process($array, $scheme, $host, $base) {
                  $this_item = array_shift($array);
                  $base = array_push($this_item);
                  if(count($array)) {
                  switch($this_item) {
                  case 'universe':
                  processGalaxy($array, $scheme, $host, $base);
                  case 'omniverse':
                  processOtherUniverseType($array, $scheme, $host, $base);
                  default:
                  throw new Exception('The specified Alternate Universe is
                  not supported');
                  }
                  } else {
                  $galaxies = Array();

                  $temp = Array();
                  $temp['display'] = 'Milkyway';
                  $temp['xlink'] = glue_url($scheme, $host, $base, 'milkyway');
                  $galaxies[] = $temp;

                  $temp = Array();
                  $temp['display'] = 'Whirlpool (M51)';
                  $temp['xlink'] = glue_url($scheme, $host, $base, 'M51');
                  $galaxies[] = $temp;

                  return Array(;
                  }
                  }

                  Based on your example, the latitude and longitude would be double
                  parsed, first to split at the ';' and then on the '='. After some
                  though, all that specific parsing is not necessary and does not allow
                  any sort of nesting beyond one level, more tokens would have to be
                  specified per level. Consider this, there is no latitude or longitude
                  designation at all, rather, use URL encoding to nest further processing,
                  such as this: 90.0%2F12.0, this would allow the next function to simply
                  URL Decode it and determine what it needs to do with it, further nesting
                  could be achieved by url encoding an already URL encoded string, at each
                  step in the processing it would naturally unravel.

                  It may even be worthwhile to simply urlencode JSON data for any given
                  node, that way a full datastructure could be passed if necessary, ableit
                  making the URL super long :)

                  The ultimate goal of all this is to remove the dang ? and & monikers.
                  Those routinely cause issues with Proxy servers, which we want to
                  maximize the use of. Without sessions and without having to worry about
                  the data chaning under our nose because the data point should either be
                  static or have the 'if modified since' flags enabled. This in its very
                  nature means that the PHP will have to respond appropirately to HEAD
                  requests.

                  That is all for now :)

                  Christian

                  Donald_Strong@... wrote:

                  > Hi Roger and Christian,
                  >
                  > > If we agree that the sole purpose of a URL is to identify a resource,
                  > > then I cannot see why a person would ever use query strings.
                  > > If information needs to be passed to the resource, then you must
                  > > ask "why?" Are you wishing to update a resource? If so, then you
                  > > should POST the information to the resource (and the resource is
                  > > identified using a logical URL without any query strings).
                  >
                  > A query URL (ie. a URL that contains a query path) is useful in a
                  > web service for the same reason it is useful in HTML; It allows the
                  > User Agent to construct a URL according to a specification provided by
                  > the Origin Server. The User Agent can then GET the representation
                  > with a high expectation that the URL will be understood and accepted.
                  >
                  > I have likened this, in the past, to asking a question of the resource.
                  > This makes sense if the resource that provided the form (input
                  > specification)
                  > is the same one the form is submitted to, eg.
                  >
                  > GET http://acme.com/aircraft
                  >
                  > <form action="/aircraft">
                  > <input type="text" name="manufacturer"/>
                  > <input type="text" name="pax_capacity"/>
                  > </form>
                  >
                  > GET http://acme.com/aircraft?manufacturer=Boeing&pax_capacity=300
                  > <http://acme.com/aircraft?manufacturer=Boeing&pax_capacity=300>
                  >
                  >
                  > > But I propose the following: http://[host <http://%5Bhost>
                  > ]///[universe]/[galaxy]/[system]/[planet]/90.0%2012.0
                  >
                  > I have also suggested using segment parameters in the past.
                  >
                  > http://acme.com/universe/milkyway/sol/earth/lat=90.0;long=12.0/30000
                  >
                  > This has the advantage that more segments can be used after the params.
                  > In this case I have specified a height or 30000 feet.
                  >
                  > Donald.
                  >
                  >
                  > ------------------------------------------------------------------------
                  > YAHOO! GROUPS LINKS
                  >
                  > * Visit your group "rest-discuss
                  > <http://groups.yahoo.com/group/rest-discuss>" on the web.
                  >
                  > * To unsubscribe from this group, send an email to:
                  > rest-discuss-unsubscribe@yahoogroups.com
                  > <mailto:rest-discuss-unsubscribe@yahoogroups.com?subject=Unsubscribe>
                  >
                  > * Your use of Yahoo! Groups is subject to the Yahoo! Terms of
                  > Service <http://docs.yahoo.com/info/terms/>.
                  >
                  >
                  > ------------------------------------------------------------------------
                  >
                • Justin T. Sampson
                  ... Comma is also legal, by the way: .../90.0,12.0 ... It occurs to me that the path part works particularly well for anything that s worth naming
                  Message 8 of 11 , Dec 2, 2005
                  • 0 Attachment
                    Donald Strong wrote:

                    > > But I propose the following:
                    > > http://[host]/[universe]/[galaxy]/[system]/[planet]/90.0%2012.0

                    Comma is also legal, by the way: .../90.0,12.0

                    > I have also suggested using segment parameters in the past.
                    >
                    > http://acme.com/universe/milkyway/sol/earth/lat=90.0;long=12.0/30000
                    >
                    > This has the advantage that more segments can be used after the
                    > params. In this case I have specified a height or 30000 feet.

                    It occurs to me that the path part works particularly well for
                    anything that's worth naming individually. While every point in
                    space could be considered a meaningful resource, not every point
                    is really worth naming. Also notice that we're starting to deal
                    with *approximate* values here. The most useful thing to do when
                    given a pair of approximate coordinates might be to produce a list
                    of things worth naming approximately at or near those coordinates.
                    In this case, putting the coordinates in the query string makes
                    perfect sense, with the response then actually naming interesting
                    sites such as...

                    == User-Agent ==
                    GET http://.../universe/milkyway/sol/earth/?lat=90.0&long=12.0
                    == Server ==
                    200

                    http://.../universe/milkyway/sol/earth/whitehouse (1000 miles)
                    http://.../universe/milkyway/sol/earth/kremlin (10000 miles)
                    http://.../universe/milkyway/sol/earth/tajmahal (15000 miles)
                    == end ==

                    But of course if the application really wants to name every point
                    in space, any of the above syntaxes is fine.

                    (I waffle about the trailing slash; it's really just an aesthetic
                    thing, but it gives some suggestion of a resource being a
                    collection, and it does make relative URIs more convenient.)

                    Cheers,
                    Justin
                  • Jack J. Coleman
                    I implemented a REST web service for administering account information. I was using a Tomcat server stand-alone. I just installed mod_jk to hook it in with
                    Message 9 of 11 , Feb 2, 2006
                    • 0 Attachment
                      I implemented a REST web service for administering account information.
                      I was using a Tomcat server stand-alone. I just installed mod_jk to hook
                      it in with Apache. I now get an error message when doing a PUT, saying
                      that PUT is not supported by Apache.

                      Has anyone on this list set up Apache with Tomcat for use with the POST
                      request-method?

                      Sorry in advance if this is a bit off topic.

                      Jack Coleman
                    • Roy T. Fielding
                      ... I suggest doing a google search. mod_jk is a servlet interface extension, so I don t know what it supports (and unfortunately I have no time to check
                      Message 10 of 11 , Feb 2, 2006
                      • 0 Attachment
                        On Feb 2, 2006, at 4:22 PM, Jack J. Coleman wrote:

                        > I implemented a REST web service for administering account
                        > information.
                        > I was using a Tomcat server stand-alone. I just installed mod_jk to
                        > hook
                        > it in with Apache. I now get an error message when doing a PUT, saying
                        > that PUT is not supported by Apache.
                        >
                        > Has anyone on this list set up Apache with Tomcat for use with the
                        > POST
                        > request-method?

                        I suggest doing a google search. mod_jk is a servlet interface
                        extension,
                        so I don't know what it supports (and unfortunately I have no time to
                        check
                        right now). PUT is supported by Apache if the module responsible for
                        handling
                        that part of the Location space allows PUT.

                        ....Roy
                      Your message has been successfully submitted and would be delivered to recipients shortly.