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

Re: [rest-discuss] This is REST

Expand Messages
  • Roy T. Fielding
    ... No. This is an application of computers to do something useful, not a math problem or a reachability analysis. Any given client might only be able to
    Message 1 of 28 , Mar 4, 2009
      On Mar 4, 2009, at 3:31 AM, Solomon Duskis wrote:
      > Thank you very much for the clarification.
      >
      > If I understand correctly, the single bookmark constraint means
      > that any initial access to the REST system must allow
      > discoverability to every accessible part of the system through some
      > degree of linkage sepration. There is some path from every point A
      > to point B and back again. There's some way to discover the entire
      > system using any entry point.
      >

      No. This is an application of computers to do something useful,
      not a math problem or a reachability analysis. Any given client
      might only be able to reach 1% of a system and still be successful
      at doing what they wanted to do. The simplest example of that is
      a system using authentication and role-based access control.

      In any case, this line of thought is missing the point of REST.
      If the application state is entirely defined by the client's
      workspace (set of representations) and all possible transitions
      away from that state are presented in those representations,
      then the potential size of the overall system is irrelevant.
      Each state can be considered independently. That is fundamental
      to the use of state machines to simplify the understanding of
      complex systems.

      The client only needs to know what it has in that workspace,
      at that time, and so any pre-definition of URI layout or
      WSDL-like service semantics is an absolute waste of time as
      far as a RESTful architecture is concerned. External artifacts
      might help the developers communicate about or improve the design
      of their system, just as readable URIs will help a human user
      understand where they are in a hypertext user-interface, but
      those external artifacts must not have a role in the runtime
      architecture if the system is truly hypertext-driven.

      ....Roy
    • Solomon Duskis
      Comments below ... Good question Darrel; it s straight to the point :). I hope that this email will answer that question. I also hope that this will either
      Message 2 of 28 , Mar 4, 2009
        Comments below

        On Wed, Mar 4, 2009 at 9:18 PM, Darrel Miller <darrel.miller@...> wrote:

        On Wed, Mar 4, 2009 at 6:31 AM, Solomon Duskis <sduskis@...> wrote:

        C) Website discover works because there's a human driving the navigation.  REST API discoverability requires a complex "discovery engine" making REST APIs too complex to discover effectively without that engine.  The barrier to entry is too big, 


         
        __,_._,_
         
        I don't understand why you believe it is difficult to get a client application to discover links.  Writing client side code to finding and follow links in an XML or HTML based document is quite trivial.

        Darrel
         
        Good question Darrel; it's straight to the point :).  I hope that this email will answer that question.  I also hope that this will either prove or disprove that I understand what Roy Fielding said in the last email to this group.

        Yes, you can create a system that can follow arbitrary XML or HTML links.  However, REST APIs are being used to build other systems.  Those system require specific functionality from the API at specific points in the interaction (a.k.a.the client workspace).  I haven't seen a working "REST API" that provides a method to derive ALL of the URLs for that timely specific functionality based on a single entry point.

        I'm going to give an example of this with a non-existant, theoretical REST API from a company called Metflix (not to be confused with any other APIs, for legal reasons).

        (Bear with me here, it's going to take some time to get to the punch line.)

        Metflix is a website that has all movies that relate to the Mets football franchise (which of course does not exist, and has no relation to any company what-so-ever).  You can:
        • login (metflix.com/login),
        • manage your Queue of Mets movies (/myqueue, as a starting point plus management functionality),
        • view a list of the latest movies (/movies/),
        • view information about a Mets movie (/movies/{id}),
        • search for Mets movies (/search?term={searchTerm}). 
        Of course there are plenty of other whiz-bang features, but we can limit our discussion to those :).

        The Metflix website got so successful, that it created a RESTful API so that other applications can be built around its services.  The URLS of the service just happen to have the same URLs as the site, but are prefixed by '/api'. 

        I want to build a fancy Flash UI client for that service, that basically exposes the same services, but just looks much nicer (Note: their affiliate program is fantastic... I'll make a ton of money that way).

        My Flash app requires the user to login, then he or she can manage the queue, search for Mets movies, and consequently view details about movies from either the queue or the search results. 

        My fancy Flash client will POST to 'metflix.com/api/login', and get a 200 status code and an auth token.  Then it will show your queue, (which as you remember, is found at '/api/myqueue' and of course the auth token has to be used here) in one panel, which has links to the individual movies in the queue, and another panel will show you latest movies (which as you remember is found at '/api/movies') which also has links to movies.  There's also a search box that performs a GET to ('/search?term=' + searchbox.text).

        (I almost got to the punchline... wait for it)

        The process of linking to invidual movies from the queue, the movie list and search results is RESTful.  You GET a list of movies (name + link) back, and can click on those links to "transition state" to view the movie details.

        The problem is that for the sake of my specific requirements, I hardcoded the URLs for the queue, the current movie list and the search box.  I didn't "discover" those URLs based on the result of my login request (which happens to be my bookmark and entry point to the system).  Notice that I also hard-coded the query parameter that needs to be used for my search term. 

        Based on my (clearly limited) understanding of REST, all of that hardcoding of URLs in my Flash UI, which is a client of the Metflix.com, is a violation of the HATEOAS/hyptertext constraint.  Based on my (personal, limited) observation, there are no RESTful APIs that implement the hypertext constraint any better. 

        Even if I did get back URLs, my Flash would still need to find the current value of a specific URL for a specific task (like the URL for the 'list of current movies', the URL for the 'movies in my queue' and the URL and the name of the query param of the search form).  The Metflix API needs to somehow provide my client with a set of URLs that I need for my next potential logical tasks (my "workspace," if I understandy Roy Fielding correctly).  It also needs to assign a means of of identifying how those URLs map to a specific functionality that's different from the URLs themselves.  For example It's not proper to expect the client to know what '/api/movies' is.  The server needs to provide another piece of well-understood information from which my Flash UI can interpret that the meaning of the '/api/movies' link is 'the current list of movies.'

        Websites, unlike REST APIs, do have a clever method of link identification... It's the natural language found between and around the '<a href="..">' and the '</a>' tags.  There's an "interpretation engine" that can understand that natural language, and discover the features of the pages, with the help of a User Agent (such as a web browser).  (BTW, the more I think about it, the more I apprciate th thought put into HTML and the rest of the REST ecosystem).

        Is there a clever universal method for identifying ALL appropriate links in a client of a REST API such that you can start with a given URL/bookmark (like login), and not have to hardcode any "workspace" URLs other than the first?  Is this identification process to complex without a human to interpret the meaning of the links? 

        Take a look at Craig McLanahan's first message in this thread... IMHO, it has some important clues to these answers :)

        Darrel
        , does that answer the question satisfactorally?

        Roy, if you're reading this, did I get it right this time?

        -Solomon Duskis
      • Ebenezer Ikonne
        ... Are you expecting that a client should guess the next state transition out of the blue? I m not sure this is possible. Some knowledge has to be
        Message 3 of 28 , Mar 4, 2009
          --- In rest-discuss@yahoogroups.com, Solomon Duskis <sduskis@...> wrote:
          >
          > Comments below
          >
          > On Wed, Mar 4, 2009 at 9:18 PM, Darrel Miller <darrel.miller@...>wrote:
          >
          > >
          > > On Wed, Mar 4, 2009 at 6:31 AM, Solomon Duskis <sduskis@...> wrote:
          > >
          > >> C) Website discover works because there's a human driving the
          > >> navigation. REST API discoverability requires a complex "discovery engine"
          > >> making REST APIs too complex to discover effectively without that engine.
          > >> The barrier to entry is too big,
          > >>
          > >
          > >
          > >
          > >> __,_._,_
          > >>
          > >
          > > I don't understand why you believe it is difficult to get a client
          > > application to discover links. Writing client side code to finding and
          > > follow links in an XML or HTML based document is quite trivial.
          > >
          > > Darrel
          > >
          >
          > Good question Darrel; it's straight to the point :). I hope that this email
          > will answer that question. I also hope that this will either prove or
          > disprove that I understand what Roy Fielding said in the last email to this
          > group.
          >
          > Yes, you can create a system that can follow *arbitrary *XML or HTML links.
          > However, REST APIs are being used to build other systems. Those system
          > require *specific functionality* from the API at *specific *points in the
          > interaction (a.k.a.the client workspace). I haven't seen a working "REST
          > API" that provides a method to derive ALL of the URLs for that timely
          > specific functionality based on a single entry point.
          >
          > I'm going to give an example of this with a non-existant, theoretical REST
          > API from a company called Metflix (not to be confused with any other APIs,
          > for legal reasons).
          >
          > (Bear with me here, it's going to take some time to get to the punch line.)
          >
          > Metflix is a website that has all movies that relate to the Mets football
          > franchise (which of course does not exist, and has no relation to any
          > company what-so-ever). You can:
          >
          > - login (metflix.com/login),
          > - manage your Queue of Mets movies (/myqueue, as a starting point plus
          > management functionality),
          > - view a list of the latest movies (/movies/),
          > - view information about a Mets movie (/movies/{id}),
          > - search for Mets movies (/search?term={searchTerm}).
          >
          > Of course there are plenty of other whiz-bang features, but we can limit our
          > discussion to those :).
          >
          > The Metflix website got so successful, that it created a RESTful API so that
          > other applications can be built around its services. The URLS of the
          > service just happen to have the same URLs as the site, but are prefixed by
          > '/api'.
          >
          > I want to build a fancy Flash UI client for that service, that basically
          > exposes the same services, but just looks much nicer (Note: their affiliate
          > program is fantastic... I'll make a ton of money that way).
          >
          > My Flash app requires the user to login, then he or she can manage the
          > queue, search for Mets movies, and consequently view details about movies
          > from either the queue or the search results.
          >
          > My fancy Flash client will POST to 'metflix.com/api/login', and get a 200
          > status code and an auth token. Then it will show your queue, (which as you
          > remember, is found at '/api/myqueue' and of course the auth token has to be
          > used here) in one panel, which has links to the individual movies in the
          > queue, and another panel will show you latest movies (which as you remember
          > is found at '/api/movies') which also has links to movies. There's also a
          > search box that performs a GET to ('/search?term=' + searchbox.text).
          >
          > (I almost got to the punchline... wait for it)
          >
          > The process of linking to invidual movies from the queue, the movie list and
          > search results is RESTful. You GET a list of movies (name + link) back, and
          > can click on those links to "transition state" to view the movie details.
          >
          > The problem is that for the sake of my specific requirements, I hardcoded
          > the URLs for the queue, the current movie list and the search box. I didn't
          > "discover" those URLs based on the result of my login request (which happens
          > to be my bookmark and entry point to the system). Notice that I also
          > hard-coded the query parameter that needs to be used for my search term.
          >
          > Based on my (clearly limited) understanding of REST, all of that hardcoding
          > of URLs in my Flash UI, which is a client of the Metflix.com, is a violation
          > of the HATEOAS/hyptertext constraint. Based on my (personal, limited)
          > observation, there are no RESTful APIs that implement the hypertext
          > constraint any better.
          >
          > Even if I did get back URLs, my Flash would still need to find the *current
          > value *of *a specific URL *for a specific task (like the URL for the 'list
          > of current movies', the URL for the 'movies in my queue' and the URL and the
          > name of the query param of the search form). The Metflix API needs to
          > somehow provide my client with a set of URLs that I need for my next
          > potential logical tasks (my "workspace," if I understandy Roy Fielding
          > correctly). It also needs to assign a means of of identifying how those
          > URLs map to a specific functionality that's different from the URLs
          > themselves. For example It's not proper to expect the client to know what
          > '/api/movies' is. The server needs to provide another piece of
          > well-understood information from which my Flash UI can *interpret *that the
          > meaning of the '/api/movies' link is 'the current list of movies.'
          >
          > Websites, unlike REST APIs, do have a clever method of link
          > identification... It's the natural language found between and around the '<a
          > href="..">' and the '</a>' tags. There's an "interpretation engine" that
          > can understand that natural language, and discover the features of the
          > pages, with the help of a User Agent (such as a web browser). (BTW, the
          > more I think about it, the more I apprciate th thought put into HTML and the
          > rest of the REST ecosystem).
          >
          > Is there a clever universal method for identifying ALL appropriate links in
          > a client of a REST API such that you can start with a given URL/bookmark
          > (like login), and not have to hardcode any "workspace" URLs other than the
          > first? Is this identification process to complex without a human to
          > interpret the meaning of the links?
          >
          > Take a look at Craig McLanahan's first message in this thread... IMHO, it
          > has some important clues to these answers :)
          > *
          > Darrel*, does that answer the question satisfactorally?
          >
          > *Roy*, if you're reading this, did I get it right this time?
          >
          > -Solomon Duskis
          >

          Are you expecting that a client should "guess" the next state transition out of the blue? I'm not sure this is possible. Some knowledge has to be provided (I think) out of band that explains "relationships" in some way such that a client can be programmed to traverse the state transitions. The key (in my opinion) is that the out of band information are not URIs but rather "identifiers" for relationships e.g. Atom uses "rel" to indicate relationships and basically monikers like "self" have meaning within the protocol.

          Eb
        • Darrel Miller
          ... of the URLs ... Here is an experimental api that accesses the MSDN documentation and the community generated content.
          Message 4 of 28 , Mar 4, 2009
            Solomon Duskis wrote:
            > I haven't seen a working "REST API" that provides a method to derive ALL of the URLs 
            > for that timely specific functionality based on a single entry point.


            Here is an experimental api that accesses the MSDN documentation and the community generated content.

            http://lab.msdn.microsoft.com/restapi/

            It uses the XHTML media type. I don't believe you need any other information to start using it.


            Ebenezer Ikonne wrote:
            > The key (in my opinion) is that the out of band information are not URIs but 
            > rather "identifiers" for relationships e.g. Atom uses "rel" to indicate relationships
            > and basically monikers like "self" have meaning within the protocol.

            Those rel values are not "out of band" they are defined in the Atom spec which is related to the media type that is returned.  To my knowledge if you want a client to interpret your own rel values you have two choices, you can create your own media-type and define the rel values or you can download code (a la AJAX) that knows what to do with those rel values.

            Darrel
          • Stefan Tilkov
            You are (almost) right I think. The difference is: Given the representation contains you don t hardcode the string
            Message 5 of 28 , Mar 4, 2009
              You are (almost) right I think. The difference is: Given the
              representation contains

              <link rel="some-concept" ref="/some-uri" />

              you don't hardcode the string "/some-uri" into your client, but rather
              the string "some-concept".

              Of course your program can't interpret new values of rel on the fly
              (unless it's some fancy AI, but let's not get there). You are of
              course better off if you use values for rel that are widely understood
              - this is the reason for efforts like this:

              http://tools.ietf.org/html/draft-nottingham-http-link-header-04

              Stefan
              --
              Stefan Tilkov, http://www.innoq.com/blog/st/



              On 05.03.2009, at 05:03, Solomon Duskis wrote:

              >
              > Comments below
              >
              > On Wed, Mar 4, 2009 at 9:18 PM, Darrel Miller
              > <darrel.miller@...> wrote:
              >
              > On Wed, Mar 4, 2009 at 6:31 AM, Solomon Duskis <sduskis@...>
              > wrote:
              > C) Website discover works because there's a human driving the
              > navigation. REST API discoverability requires a complex "discovery
              > engine" making REST APIs too complex to discover effectively without
              > that engine. The barrier to entry is too big,
              >
              >
              >
              > __,_._,_
              >
              > I don't understand why you believe it is difficult to get a client
              > application to discover links. Writing client side code to finding
              > and follow links in an XML or HTML based document is quite trivial.
              >
              > Darrel
              >
              > Good question Darrel; it's straight to the point :). I hope that
              > this email will answer that question. I also hope that this will
              > either prove or disprove that I understand what Roy Fielding said in
              > the last email to this group.
              >
              > Yes, you can create a system that can follow arbitrary XML or HTML
              > links. However, REST APIs are being used to build other systems.
              > Those system require specific functionality from the API at specific
              > points in the interaction (a.k.a.the client workspace). I haven't
              > seen a working "REST API" that provides a method to derive ALL of
              > the URLs for that timely specific functionality based on a single
              > entry point.
              >
              > I'm going to give an example of this with a non-existant,
              > theoretical REST API from a company called Metflix (not to be
              > confused with any other APIs, for legal reasons).
              >
              > (Bear with me here, it's going to take some time to get to the punch
              > line.)
              >
              > Metflix is a website that has all movies that relate to the Mets
              > football franchise (which of course does not exist, and has no
              > relation to any company what-so-ever). You can:
              > • login (metflix.com/login),
              > • manage your Queue of Mets movies (/myqueue, as a starting point
              > plus management functionality),
              > • view a list of the latest movies (/movies/),
              > • view information about a Mets movie (/movies/{id}),
              > • search for Mets movies (/search?term={searchTerm}).
              > Of course there are plenty of other whiz-bang features, but we can
              > limit our discussion to those :).
              >
              > The Metflix website got so successful, that it created a RESTful API
              > so that other applications can be built around its services. The
              > URLS of the service just happen to have the same URLs as the site,
              > but are prefixed by '/api'.
              >
              > I want to build a fancy Flash UI client for that service, that
              > basically exposes the same services, but just looks much nicer
              > (Note: their affiliate program is fantastic... I'll make a ton of
              > money that way).
              >
              > My Flash app requires the user to login, then he or she can manage
              > the queue, search for Mets movies, and consequently view details
              > about movies from either the queue or the search results.
              >
              > My fancy Flash client will POST to 'metflix.com/api/login', and get
              > a 200 status code and an auth token. Then it will show your queue,
              > (which as you remember, is found at '/api/myqueue' and of course the
              > auth token has to be used here) in one panel, which has links to the
              > individual movies in the queue, and another panel will show you
              > latest movies (which as you remember is found at '/api/movies')
              > which also has links to movies. There's also a search box that
              > performs a GET to ('/search?term=' + searchbox.text).
              >
              > (I almost got to the punchline... wait for it)
              >
              > The process of linking to invidual movies from the queue, the movie
              > list and search results is RESTful. You GET a list of movies (name
              > + link) back, and can click on those links to "transition state" to
              > view the movie details.
              >
              > The problem is that for the sake of my specific requirements, I
              > hardcoded the URLs for the queue, the current movie list and the
              > search box. I didn't "discover" those URLs based on the result of
              > my login request (which happens to be my bookmark and entry point to
              > the system). Notice that I also hard-coded the query parameter that
              > needs to be used for my search term.
              >
              > Based on my (clearly limited) understanding of REST, all of that
              > hardcoding of URLs in my Flash UI, which is a client of the
              > Metflix.com, is a violation of the HATEOAS/hyptertext constraint.
              > Based on my (personal, limited) observation, there are no RESTful
              > APIs that implement the hypertext constraint any better.
              >
              > Even if I did get back URLs, my Flash would still need to find the
              > current value of a specific URL for a specific task (like the URL
              > for the 'list of current movies', the URL for the 'movies in my
              > queue' and the URL and the name of the query param of the search
              > form). The Metflix API needs to somehow provide my client with a
              > set of URLs that I need for my next potential logical tasks (my
              > "workspace," if I understandy Roy Fielding correctly). It also
              > needs to assign a means of of identifying how those URLs map to a
              > specific functionality that's different from the URLs themselves.
              > For example It's not proper to expect the client to know what '/api/
              > movies' is. The server needs to provide another piece of well-
              > understood information from which my Flash UI can interpret that the
              > meaning of the '/api/movies' link is 'the current list of movies.'
              >
              > Websites, unlike REST APIs, do have a clever method of link
              > identification... It's the natural language found between and around
              > the '<a href="..">' and the '</a>' tags. There's an "interpretation
              > engine" that can understand that natural language, and discover the
              > features of the pages, with the help of a User Agent (such as a web
              > browser). (BTW, the more I think about it, the more I apprciate th
              > thought put into HTML and the rest of the REST ecosystem).
              >
              > Is there a clever universal method for identifying ALL appropriate
              > links in a client of a REST API such that you can start with a given
              > URL/bookmark (like login), and not have to hardcode any "workspace"
              > URLs other than the first? Is this identification process to
              > complex without a human to interpret the meaning of the links?
              >
              > Take a look at Craig McLanahan's first message in this thread...
              > IMHO, it has some important clues to these answers :)
              >
              > Darrel, does that answer the question satisfactorally?
              >
              > Roy, if you're reading this, did I get it right this time?
              >
              > -Solomon Duskis
              >
              >
              > <!-- #ygrp-mkp{ border: 1px solid #d8d8d8; font-family: Arial;
              > margin: 14px 0px; padding: 0px 14px; } #ygrp-mkp hr{ border: 1px
              > solid #d8d8d8; } #ygrp-mkp #hd{ color: #628c2a; font-size: 85%; font-
              > weight: bold; line-height: 122%; margin: 10px 0px; } #ygrp-mkp
              > #ads{ margin-bottom: 10px; } #ygrp-mkp .ad{ padding: 0 0; } #ygrp-
              > mkp .ad a{ color: #0000ff; text-decoration: none; } --> <!-- #ygrp-
              > sponsor #ygrp-lc{ font-family: Arial; } #ygrp-sponsor #ygrp-lc
              > #hd{ margin: 10px 0px; font-weight: bold; font-size: 78%; line-
              > height: 122%; } #ygrp-sponsor #ygrp-lc .ad{ margin-bottom: 10px;
              > padding: 0 0; } --> <!-- #ygrp-mlmsg {font-size:13px; font-family:
              > arial,helvetica,clean,sans-serif;*font-size:small;*font:x-small;}
              > #ygrp-mlmsg table {font-size:inherit;font:100%;} #ygrp-mlmsg select,
              > input, textarea {font:99% arial,helvetica,clean,sans-serif;} #ygrp-
              > mlmsg pre, code {font:115% monospace;*font-size:100%;} #ygrp-mlmsg *
              > {line-height:1.22em;} #ygrp-text{ font-family: Georgia; } #ygrp-
              > text p{ margin: 0 0 1em 0; } dd.last p a { font-family: Verdana;
              > font-weight: bold; } #ygrp-vitnav{ padding-top: 10px; font-family:
              > Verdana; font-size: 77%; margin: 0; } #ygrp-vitnav a{ padding: 0
              > 1px; } #ygrp-mlmsg #logo{ padding-bottom: 10px; } #ygrp-reco
              > { margin-bottom: 20px; padding: 0px; } #ygrp-reco #reco-head { font-
              > weight: bold; color: #ff7900; } #reco-category{ font-size: 77%; }
              > #reco-desc{ font-size: 77%; } #ygrp-vital a{ text-decoration:
              > none; } #ygrp-vital a:hover{ text-decoration: underline; } #ygrp-
              > sponsor #ov ul{ padding: 0 0 0 8px; margin: 0; } #ygrp-sponsor #ov
              > li{ list-style-type: square; padding: 6px 0; font-size: 77%; } #ygrp-
              > sponsor #ov li a{ text-decoration: none; font-size: 130%; } #ygrp-
              > sponsor #nc{ background-color: #eee; margin-bottom: 20px;
              > padding: 0 8px; } #ygrp-sponsor .ad{ padding: 8px 0; } #ygrp-
              > sponsor .ad #hd1{ font-family: Arial; font-weight: bold; color:
              > #628c2a; font-size: 100%; line-height: 122%; } #ygrp-sponsor .ad
              > a{ text-decoration: none; } #ygrp-sponsor .ad a:hover{ text-
              > decoration: underline; } #ygrp-sponsor .ad p{ margin: 0; } o{font-
              > size: 0; } .MsoNormal{ margin: 0 0 0 0; } #ygrp-text tt{ font-size:
              > 120%; } blockquote{margin: 0 0 0 4px;} .replbq{margin:4} dd.last p
              > span { margin-right: 10px; font-family: Verdana; font-weight:
              > bold; } dd.last p span.yshortcuts { margin-right: 0; } div.photo-
              > title a, div.photo-title a:active, div.photo-title a:hover,
              > div.photo-title a:visited { text-decoration: none; } div.file-title
              > a, div.file-title a:active, div.file-title a:hover, div.file-title
              > a:visited { text-decoration: none; } #ygrp-msg p { clear: both;
              > padding: 15px 0 3px 0; overflow: hidden; } #ygrp-msg p span { color:
              > #1E66AE; font-weight: bold; } div#ygrp-mlmsg #ygrp-msg p a
              > span.yshortcuts { font-family: Verdana; font-size: 10px; font-
              > weight: normal; } #ygrp-msg p a { font-family: Verdana; font-size:
              > 10px; } #ygrp-mlmsg a { color: #1E66AE; } div.attach-table div div a
              > { text-decoration: none; } div.attach-table { width: 400px; } -->
            • Solomon Duskis
              *RE: XHTML *It looks like a promising foundation for RESTful API Media Types. You have a whole bunch of class= on your tags (plus other
              Message 6 of 28 , Mar 5, 2009
                RE: XHTML
                It looks like a promising foundation for RESTful API Media Types.  You have a whole bunch of class="<some identifier>" on your <a> tags (plus other tags) that a programmatic client can use to identify the meaning link (rather than relying on the href itself). 

                I do think that HTML is the media to emulate.  "class" is used successfully to perform the kind of semantic markup that atom's "rel" has.  "class" can also be multi-valued (which I don't know if that's possible with "rel") and is currently used by programmatic constructs to infer meaning outside of the href.  "class" also has HTML siblings in the task of identification.  There's also the "id" tag in the "a" element, the body of the "a" element, and "<label for=''>...</label>" for form elements.  RESTful API Media Types need a way to integrate these types of tactics in a consistent way.

                Beyond the Media Type issues, another thing that needs to be explored is how to use this information the the client side for non-browser clients.  The programmatic constructs that use "class" (such as JavaScript, and even CSS) usually fall under the role of code-on-demand, but the general techniques can be used for programmatic constructs that fill the role of remote client.  Once we have a consistent approach to Media Types, we can start constructing "User Agent" APIs that ease the task of traversing specific RESTful API Media Types that share common elements of semantic markup. 

                RE: I don't believe you need any other information to start using it.

                Before a programmatic client can perform a specific task it must either know a single "class" value , or a set of "class" values to follow.  IMHO, that's shared "out of band" information, but it's not driving the interaction; meaning those semantics are the crux of what you need to know to interact, but they don't define lower-level URI construction semantics.  A bookmark + shared media types + shared semantics should provide a way for the client can discover the specific resources it needs from the server.

                you can create your own media-type and define the rel values 

                I'm not going to put words in your mouth, but it sounds like there needs to be a shared understanding of semantics.  That shared understanding can come from a community consensus like Stefan Tikolov suggests:

                Of course your program can't interpret new values of rel on the fly (unless it's some fancy AI, but let's not get there). You are of
                course better off if you use values for rel that are widely understood - this is the reason for efforts like this:

                http://tools.ietf.org/html/draft-nottingham-http-link-header-04

                It's also perfectly legitimate for a RESTful API to create its own dictionary of values, along with its own Media Types.  It may also provide a few entry points for different client types.  Those should the likely be the only items on a RESTful API documentation page :).  (It's also likely that the API will have a set of example URLs to show some specific functionality, but should discourage clients from using those URLs directly, and encourage the use of semantics)

                or you can download code (a la AJAX) that knows what to do with those rel values that knows what to do with those rel values.

                I agree that this is a great option and should be explored, especially outside the generic web browser.  Like I said earlier, I can see a great place for "User Agent" platforms that know about a common Media Type rules and knows how run ubiquitous scripting languages... More on that later :)


                Thanks for the discussion guys!  This has been greatly enlightening.

                -Solomon

                On Thu, Mar 5, 2009 at 12:50 AM, Darrel Miller <darrel.miller@...> wrote:

                Solomon Duskis wrote:
                > I haven't seen a working "REST API" that provides a method to derive ALL of the URLs 
                > for that timely specific functionality based on a single entry point.


                Here is an experimental api that accesses the MSDN documentation and the community generated content.

                http://lab.msdn.microsoft.com/restapi/

                It uses the XHTML media type. I don't believe you need any other information to start using it.


                Ebenezer Ikonne wrote:
                > The key (in my opinion) is that the out of band information are not URIs but 
                > rather "identifiers" for relationships e.g. Atom uses "rel" to indicate relationships
                > and basically monikers like "self" have meaning within the protocol.

                Those rel values are not "out of band" they are defined in the Atom spec which is related to the media type that is returned.  To my knowledge if you want a client to interpret your own rel values you have two choices, you can create your own media-type and define the rel values or you can download code (a la AJAX) that knows what to do with those rel values.

                Darrel

              • Ebenezer Ikonne
                ... Well in a sense they are, because the protocol exists in text that is outside of the client. The client is not determining what rel inline, its
                Message 7 of 28 , Mar 5, 2009
                  > Those rel values are not "out of band" they are defined in the Atom spec
                  > which is related to the media type that is returned. To my knowledge if you
                  > want a client to interpret your own rel values you have two choices, you can
                  > create your own media-type and define the rel values or you can download
                  > code (a la AJAX) that knows what to do with those rel values.
                  >
                  > Darrel
                  >

                  Well in a sense they are, because the protocol exists in text that is outside of the client. The client is not determining what "rel" inline, its programmed with a priori knowledge of the transitions. provided by all "rel" values.

                  Having said that, I think we're splitting hairs here. :)
                • Darrel Miller
                  Here is an interesting survey of rel values in use on the web. http://blog.unto.net/web/a-survey-of-rel-values-on-the-web/ ... Yes the client must understand
                  Message 8 of 28 , Mar 5, 2009
                    Here is an interesting survey of rel values in use on the web.

                    http://blog.unto.net/web/a-survey-of-rel-values-on-the-web/
                    Excerpt:
                    >  found a staggering 1.8M unique rel value strings in use, with many used only once or
                    > twice across all the web. In fact, the top 6 most-frequently-used rel values accounted
                    > for 80% of all usage, and the top 11 alone were responsible for 90% of all usage.


                    On Thu, Mar 5, 2009 at 7:39 AM, Ebenezer Ikonne <amaeze@...> wrote:
                    >
                    > Well in a sense they are, because the protocol exists in text that is outside of the client.
                    > The client is not determining what "rel" inline, its programmed with a priori knowledge of the
                    > transitions. provided by all "rel" values.
                    >

                    Yes the client must understand the media type before hand.  However
                    the significant difference is that when the client follows a link, the
                    media-type is in the header of the response.  The client knows how to
                    parse the message based only on the content of the message and its
                    prior knowledge of the media type.  In so many so called "RESTful"
                    API's that I see the client retrieves application/xml from endpoint
                    http://site.org/xyz and it must know that the application/xml at this
                    endpoint contains a specific vocabulary.

                    Darrel
                  • Ebenezer Ikonne
                    ... I think we are in some agreement here. Now the debate for whether to use generic media-types versus specific media-types is slightly different (IMO). I
                    Message 9 of 28 , Mar 5, 2009
                      > Yes the client must understand the media type before hand. �However
                      > the significant difference is that when the client follows a link, the
                      > media-type is in the header of the response. �The client knows how to
                      > parse the message based only on the content of the message and its
                      > prior knowledge of the media type. �In so many so called "RESTful"
                      > API's that I see the client retrieves application/xml from endpoint
                      > http://site.org/xyz and it must know that the application/xml at this
                      > endpoint contains a specific vocabulary.
                      >
                      > Darrel
                      >

                      I think we are in some agreement here. Now the debate for whether to use generic media-types versus specific media-types is slightly different (IMO). I believe in specific media-types, but in both cases, a priori is still required. The flexibility of the client is severely hampered when using generic media-types.

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